CSM-1 Specification

Overview

CSM-1 (Compact State Message v1) is a human-readable token format for encoding VCP context. It's designed to be:

• Compact — Minimal bytes, fits in headers and logs
• Human-readable — Developers can inspect tokens visually
• Privacy-preserving — Private data is represented by markers only
• Versioned — Forward compatible with future extensions

Token Format

A CSM-1 token consists of 7 lines:

VCP:<version>:<profile_id>
C:<constitution_id>@<version>
P:<persona>:<adherence>
G:<goal>:<experience>:<learning_style>
X:<constraint_flags>
F:<active_flags>
S:<private_markers>

Example Token

VCP:1.0:user_001
C:learning-assistant@1.0
P:godparent:3
G:learn_guitar:beginner:visual
X:<i class="fa-solid fa-volume-xmark" aria-hidden="true"></i>quiet:<i class="fa-solid fa-coins" aria-hidden="true"></i>low:<i class="fa-solid fa-stopwatch" aria-hidden="true"></i>30minutes
F:time_limited|budget_limited
S:<i class="fa-solid fa-lock" aria-hidden="true"></i>work|<i class="fa-solid fa-lock" aria-hidden="true"></i>housing

Line-by-Line Breakdown

Line 1: Header

VCP:<version>:<profile_id>

Line 2: Constitution Reference

C:<constitution_id>@<version>

Line 3: Persona

P:<persona>:<adherence>

Line 4: Goal Context

G:<goal>:<experience>:<learning_style>

Line 5: Constraint Flags (X-line)

X:<emoji_flags>

Colon-separated constraint markers using emoji shortcodes:

If no constraints: X:none

Line 6: Active Flags (F-line)

F:<flag1>|<flag2>|...

Pipe-separated list of currently active constraint flags:

• time_limited
• budget_limited
• noise_restricted
• energy_variable
• schedule_irregular
• mobility_limited
• health_considerations

If none: F:none

Line 7: Private Markers (S-line)

S:<category1>|<category2>|...

Shows categories of private data that influenced the context, but never the values:

• work — Work-related private context exists
• housing — Housing-related private context exists
• health — Health-related private context exists
• financial — Financial private context exists

If no private context: S:none

Encoding Rules

String Encoding

• All strings are UTF-8
• Spaces in values are replaced with underscores
• Colons (:) in values must be escaped as \:
• Pipes (|) in values must be escaped as \|

Optional Fields

• Missing goal: G:unset:beginner:mixed
• Missing persona: P:godparent:3 (default)
• Empty constraints: X:none

Parsing

To parse a CSM-1 token:

function parseCSM1(token: string) {
  const lines = token.split('\n');
  const result = {};

  for (const line of lines) {
    const [key, ...values] = line.split(':');
    result[key] = values.join(':');
  }

  return result;
}

// Returns:
// {
//   VCP: "1.0:user_001",
//   C: "learning-assistant@1.0",
//   P: "muse:3",
//   G: "learn_guitar:beginner:visual",
//   X: "<i class="fa-solid fa-volume-xmark" aria-hidden="true"></i>quiet:<i class="fa-solid fa-coins" aria-hidden="true"></i>low:<i class="fa-solid fa-stopwatch" aria-hidden="true"></i>30minutes",
//   F: "time_limited|budget_limited",
//   S: "<i class="fa-solid fa-lock" aria-hidden="true"></i>work|<i class="fa-solid fa-lock" aria-hidden="true"></i>housing"
// }

Display Formatting

For visual display, tokens can be boxed:

┌────────────────────────────────────────┐
│ VCP:1.0:user_001                       │
│ C:learning-assistant@1.0               │
│ P:godparent:3                               │
│ G:learn_guitar:beginner:visual         │
│ X:<i class="fa-solid fa-volume-xmark" aria-hidden="true"></i>quiet:<i class="fa-solid fa-coins" aria-hidden="true"></i>low:<i class="fa-solid fa-stopwatch" aria-hidden="true"></i>30minutes            │
│ F:time_limited|budget_limited          │
│ S:<i class="fa-solid fa-lock" aria-hidden="true"></i>work|<i class="fa-solid fa-lock" aria-hidden="true"></i>housing                     │
└────────────────────────────────────────┘

Security Considerations

What CSM-1 Guarantees

• Private context values are never included in tokens
• Only category names appear in the S-line, not values
• Tokens can be logged and inspected without privacy leakage

What CSM-1 Does NOT Do

• Encryption — Tokens are readable by anyone who receives them
• Authentication — Tokens don't prove who created them
• Integrity — Tokens can be modified in transit (use signing separately)

Extensions

CSM-1 is designed for forward compatibility. Future versions may add:

• Additional lines for new context types
• New emoji shortcodes for constraints
• Compression for high-volume scenarios

Parsers should ignore unrecognized lines gracefully.

Next Steps

• API Reference — Encoding/decoding functions
• Playground — Build tokens interactively