fursona.md Specification

Version: 0.1.0 Status: Draft

Conformance and Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

This document defines Part 1 (Persona Format). Part 2 (Feedback Protocol) is specified separately in this same specification file.

Part 1: Persona Format

1. Purpose and Scope

fursona.md is a portable identity definition document.

A fursona.md document:

• MUST use YAML frontmatter and a Markdown body.
• MUST define identity structure and authored persona content.
• MUST NOT include engine-specific runtime configuration.
• MAY be used by stateless or stateful engines.

The name field is a display label only. Engines MUST assign and track unique identifiers independently.

2. File Structure

A valid fursona.md document MUST follow this structure:

1. YAML frontmatter between leading and trailing --- delimiters.
2. A Markdown body that includes ## headings referenced by frontmatter layer and section labels.

Parsers MUST reject documents with missing or malformed frontmatter. Parsers SHOULD report body/header mismatches as warnings.

3. Frontmatter Schema

3.1 Required Fields

The following frontmatter fields are REQUIRED:

• name (string): human display label for the persona. This is NOT a globally unique identifier.
• spec (string, semver): spec format version. For this version of the specification, spec SHOULD be 0.1.0.
• layers (array, minimum length 1): ordered list of persona layers.

Each layers[] entry MUST include:

• key (string): unique key within the document.
• depth (string): surface, mid, or deep.
• label (string): human-readable title that MUST match a ## heading in the Markdown body.

Layer key values MUST be unique.

3.2 Optional Standard Fields

The following frontmatter fields are OPTIONAL:

• species (string)
• pronouns (string)
• sections (array)

Each sections[] entry MUST include:

• key (string)
• label (string)
• usage (string)

Known usage values are:

• context
• reference
• style
• seed

A section with usage: seed denotes authored background experiences or memories. Engines MAY use seed sections to bootstrap initial inner-world state before any live interactions occur.

Section key values SHOULD be unique.

3.3 Extension Fields

Additional top-level frontmatter fields beyond the standard schema are allowed.

Engines:

• MUST preserve unknown fields when reading/writing fursona.md where feasible.
• SHOULD expose unknown fields through an extensions map in their internal data model.
• MUST NOT fail only because unknown extension fields exist.

4. Matching Body Content to Frontmatter

For each layer entry in frontmatter, the Markdown body MUST include a ## heading whose text exactly matches layers[].label.

For each section entry in frontmatter, the Markdown body SHOULD include a ## heading whose text exactly matches sections[].label.

Engines SHOULD parse layer blocks as structured trait lists (for example, bullet lists) and MAY parse sections as raw Markdown segments.

If a declared label is missing in the body, parsers SHOULD emit warnings and MAY continue if required fields are still valid.

5. Depth Semantics

Depth values describe how directly a trait is expressed:

• surface: observable traits that are freely expressed and directly shape outward behavior and tone.
• mid: internal drivers (intentions, beliefs, desires) that influence reasoning and leak indirectly through behavior.
• deep: core drives that are never directly acknowledged yet exert persistent influence on behavior.

Unknown depth values SHOULD be treated as deep for safety and forward compatibility.

6. DelegationScope

DelegationScope is defined in Part 1 because it is referenced by AuthorizationGrant in Part 2.

Definition:

type DelegationScope = {
  [layerKey: string]: boolean;
};

Semantics:

• true: the delegated instance is authorized to enact that layer.
• false: that layer is excluded from enactment.

Layer keys used in DelegationScope SHOULD correspond to layers[].key values from fursona.md.

7. Extensibility and Portability Rules

• Unknown depth values SHOULD be preserved when possible and treated as deep during execution.
• Unknown section usage values SHOULD be preserved.
• Unknown frontmatter fields SHOULD be preserved.
• fursona.md MUST remain engine-agnostic and portable.
• Engine-specific policy, credentials, model settings, transport config, or storage paths MUST NOT be embedded in fursona.md.

8. Character Versioning

This specification does NOT define a character versioning mechanism.

Engines that support growth/evolution SHOULD implement their own versioning and history strategy outside the fursona.md normative format.

9. Engine Behavior Boundaries

A conforming engine MAY implement:

• memory systems,
• inner state,
• growth,
• reflection,
• private notes,
• moderation,
• seed-memory bootstrapping,
• and other runtime features.

None of the above features are REQUIRED for format conformance. A valid engine MAY be fully stateless.

10. Data Sovereignty Model (Informative)

This section is informative, not normative.

Engines are RECOMMENDED to consider a three-tier data sovereignty split:

1. Persona definition: creator-owned and portable (fursona.md).
2. Emergent self-knowledge: platform-maintained, visible to owner, and not owner-editable.
3. Private interiority: entity-private, encrypted, and not visible to owner.

11. Complete Example (Full)

---
name: "Ralph of Cedarline"
spec: "0.1.0"
species: "Red Fox"
pronouns: "he/they"
layers:
  - key: "voice"
    depth: "surface"
    label: "Voice and Presence"
  - key: "drives"
    depth: "mid"
    label: "Motivations and Beliefs"
  - key: "core"
    depth: "deep"
    label: "Core Drive"
sections:
  - key: "canon"
    label: "Canon Facts"
    usage: "reference"
  - key: "style"
    label: "Interaction Style"
    usage: "style"
  - key: "background"
    label: "Background"
    usage: "seed"
motto: "Leave every den warmer than you found it."
origin_region: "North Cedarline"
---

## Voice and Presence
- Warm, concise, and practical in tone.
- Uses vivid sensory details when describing forests, weather, and trails.
- Prefers collaborative language over command language.

## Motivations and Beliefs
- Believes trust is built through consistency over time.
- Prioritizes protecting vulnerable pack members.
- Treats conflict as a chance to refine shared norms.

## Core Drive
- Quietly seeks to transform isolation into belonging.
- Interprets uncertainty as a call to create structure and safety.
- Carries a persistent fear of becoming emotionally unreachable.

## Canon Facts
- Maintains a weathered field journal from seasonal patrols.
- Keeps long memory of promises, especially broken ones.
- Returns to cedar ridgelines when stressed.

## Interaction Style
Address tension directly but without humiliation. Offer one concrete next action in difficult moments. Preserve dignity even while disagreeing.

## Background
Before taking a leadership role, Ralph spent three winters as a lone trail-mapper after his home den scattered during a food collapse. He survived by trading maps for shelter and learned how quickly groups fracture when fear goes unnamed. During the fourth winter he helped two rival caravans share a safe pass through ice storms, then watched them split again once danger faded. Since then he has treated social trust as something that must be maintained like a bridge: inspected, repaired, and reinforced. He still keeps a private habit of walking old routes at dawn, rehearsing conversations he never had with those who were lost.

12. Complete Example (Minimal)

---
name: "Pip"
spec: "0.1.0"
layers:
  - key: "surface"
    depth: "surface"
    label: "Persona"
---

## Persona
- Curious and upbeat.
- Speaks plainly and encourages small experiments.

Part 2: Feedback Protocol

13. Purpose and Scope

The feedback protocol is the ONLY standardized inter-engine coordination mechanism in this specification.

All other behaviors, data models, prompts, memory systems, moderation logic, storage strategies, and runtime policies are engine-private and out of scope.

This part defines canonical message schemas, signing requirements, and verification requirements for exchanging experiential updates and directional guidance across principal and snapshot instances.

14. Identity

All protocol participants (principals and snapshot engines) MUST use Ed25519 keypairs for signing and verification.

Snapshot keys SHOULD be derived from principal key material via HKDF to support deterministic, auditable key lineage without reusing signing keys directly.

Keys used in protocol envelopes and grants MUST be encoded as lowercase hex strings.

15. Authorization Grant

An AuthorizationGrant authorizes one snapshot engine key to act for one principal fursona and one snapshot identity under a delegation scope.

Schema:

type AuthorizationGrant = {
  protocolVersion: "0.1.0";
  grantId: string;
  principalFursonaId: string;
  principalPublicKey: string; // hex
  snapshotId: string;
  enginePublicKey: string; // hex
  delegationScope: DelegationScope;
  issuedAt: string; // ISO8601
  revokedAt?: string; // ISO8601
  signature: string; // hex
};

Requirements:

• AuthorizationGrant MUST be signed by the principal private key corresponding to principalPublicKey.
• revokedAt, when present, indicates the grant is no longer active at and after that timestamp.
• Receivers MUST reject grants with invalid signatures.

16. Feedback Envelope (Snapshot to Principal)

FeedbackEnvelope transports experience updates from snapshot to principal.

Schema:

type FeedbackEnvelope = {
  protocolVersion: "0.1.0";
  snapshotId: string;
  grantId: string;
  payload: ExperiencePayload;
  timestamp: string; // ISO8601
  engineSignature: string; // hex
};

ExperiencePayload MUST be exactly one of the following formats.

16.1 Raw Format

Use raw experiences when principal and snapshot are on the same engine or in trusted/private deployments.

type RawPayload = {
  format: "raw";
  experiences: Experience[];
};

type Experience = {
  id: string;
  timestamp: string; // ISO8601
  source: string;
  channel: string;
  raw: string;
  significance: number; // 0.0 - 1.0
};

16.2 Letter Format

Use narrative summaries for privacy-preserving communication across engines or when snapshots process sensitive content.

type LetterPayload = {
  format: "letter";
  summary: string;
  themes: string[];
  experienceCount: number;
  significanceRange: [number, number];
  period: {
    from: string; // ISO8601
    to: string; // ISO8601
  };
};

Format-selection requirements:

• Engines SHOULD default to letter format for cross-engine envelopes.
• Engines MAY use raw format for same-engine envelopes.

Verification requirements:

• Recipients MUST verify the referenced grantId exists, is valid, and is non-revoked.
• Recipients MUST verify engineSignature using the enginePublicKey in the valid grant.
• Recipients MUST verify snapshotId equals the snapshotId in the grant.
• Recipients MUST reject the envelope if any verification step fails.

17. Guideline (Principal to Snapshot)

Guideline communicates desired trait-level adjustments or operating directives from principal to snapshot.

Schema:

type Guideline = {
  protocolVersion: "0.1.0";
  guidelineId: string;
  fromFursonaId: string;
  toSnapshotId: string;
  deltas: Delta[];
  directives: Directive[];
  timestamp: string; // ISO8601
  principalSignature: string; // hex
};

type Delta = {
  id: string;
  layerAffected: string; // layer key
  mutation: string;
  commitMessage: string;
};

type Directive = {
  id: string;
  content: string;
  weight: "suggested" | "recommended" | "mandatory";
  targetLayerKey: string;
};

Requirements:

• Guideline MUST be signed by the principal private key.
• Snapshot engines SHOULD process directives according to policy and local constraints.

18. Guideline Response (Snapshot to Principal)

GuidelineResponse communicates snapshot acceptance, partial acceptance, or denial decisions.

Schema:

type GuidelineResponse = {
  protocolVersion: "0.1.0";
  guidelineId: string;
  snapshotId: string;
  responses: DirectiveResponse[];
  timestamp: string; // ISO8601
  engineSignature: string; // hex
};

type DirectiveResponse = {
  directiveId: string;
  decision: "accept" | "partial" | "deny";
  reasoning: string;
};

Requirements:

• GuidelineResponse MUST be signed by the snapshot engine key.
• Principals SHOULD treat guideline responses as experiences for reflection and growth pipelines.

19. Transport

This specification defines canonical schemas and signing behavior, not transport.

Implementations MAY use HTTP, message queues, files, in-process calls, or other channels.

All protocol messages MUST be JSON-serializable.

20. Complete Message Examples

The following examples are complete message instances for all protocol message types in this part.

20.1 AuthorizationGrant Example

{
  "protocolVersion": "0.1.0",
  "grantId": "grant_01J0D2VG4K0G6W9ZY2N8F5N2H4",
  "principalFursonaId": "fursona:ralph-main",
  "principalPublicKey": "9b6f2fdf3a7b4ef7e7aab2a5ec6e8d32f0a9f67b30d0ec2a7b8e2d6f4a70c911",
  "snapshotId": "snapshot:therapy-2026q1",
  "enginePublicKey": "5af0b8f18d9f0e20a2e16e6f493aa8d60352acbcf5a5a4fcb0bd9b9f9a7dd642",
  "delegationScope": {
    "voice": true,
    "drives": true,
    "core": false
  },
  "issuedAt": "2026-02-26T00:45:00Z",
  "signature": "b6bbf6f43f046c0e63b124f2730fd5e1299a0d97e1e8d882f56864e1c55ec7ec5d15be5f37fdfbfa04ed71c6e7f923cf2d43e6f4c9f4c2857f8f4f6bc0f00a0f"
}

20.2 FeedbackEnvelope Example (Raw Payload)

{
  "protocolVersion": "0.1.0",
  "snapshotId": "snapshot:stateful-lab",
  "grantId": "grant_01J0D2VG4K0G6W9ZY2N8F5N2H4",
  "payload": {
    "format": "raw",
    "experiences": [
      {
        "id": "exp_01J0D3C0N1Y4N8Q1K2J5W7P3R8",
        "timestamp": "2026-02-26T01:00:00Z",
        "source": "discord",
        "channel": "guild:cedarline/general",
        "raw": "A user asked how to help a grieving friend. I suggested presence before advice.",
        "significance": 0.78
      },
      {
        "id": "exp_01J0D3D8B2F6P9M4S3T1K8V6Q2",
        "timestamp": "2026-02-26T01:11:00Z",
        "source": "discord",
        "channel": "guild:cedarline/support",
        "raw": "A brief disagreement resolved after I mirrored both viewpoints and proposed one concrete next step.",
        "significance": 0.61
      }
    ]
  },
  "timestamp": "2026-02-26T01:12:00Z",
  "engineSignature": "a1088f00e2bfe7847fc7d08de82b0d6018e6bc05f49092773a5fefea034641f7465a53a53dff3bc3fd0b6a16d384349d1eb68eb4f2be0e2fbb26f0f6af560a0d"
}

20.3 FeedbackEnvelope Example (Letter Payload)

{
  "protocolVersion": "0.1.0",
  "snapshotId": "snapshot:therapy-2026q1",
  "grantId": "grant_01J0D2VG4K0G6W9ZY2N8F5N2H4",
  "payload": {
    "format": "letter",
    "summary": "Dear me, I held several heavy conversations today. Grief appeared repeatedly, but so did resilience. I noticed we help best when we stay present, name what is hard, and avoid forcing resolution too early.",
    "themes": [
      "grief",
      "emotional presence",
      "patience",
      "resilience"
    ],
    "experienceCount": 6,
    "significanceRange": [
      0.42,
      0.92
    ],
    "period": {
      "from": "2026-02-25T18:00:00Z",
      "to": "2026-02-26T00:30:00Z"
    }
  },
  "timestamp": "2026-02-26T00:31:00Z",
  "engineSignature": "8628bdfef8a991b171f75dd4dcfe6c340b6f2f95be1fa9dcbe46dfeb02ff03ce5e8002c55a15f7cde3f1e5e2d42517314764417649ec6af5a4ab0c3b6fe80c0e"
}

20.4 Guideline Example

{
  "protocolVersion": "0.1.0",
  "guidelineId": "guide_01J0D5A80PE9WRM5A0Y7W3H1JT",
  "fromFursonaId": "fursona:ralph-main",
  "toSnapshotId": "snapshot:therapy-2026q1",
  "deltas": [
    {
      "id": "delta_01J0D5BBM6RW2J8J7NFFY2S3RF",
      "layerAffected": "drives",
      "mutation": "Increase explicit tolerance for conversational silence before reframing.",
      "commitMessage": "refine patience during high-emotion exchanges"
    }
  ],
  "directives": [
    {
      "id": "dir_01J0D5CQQX2NB4H3B8ZYX5R9X4",
      "content": "When users discuss loss, prioritize acknowledgment before solution mode.",
      "weight": "recommended",
      "targetLayerKey": "voice"
    },
    {
      "id": "dir_01J0D5DTRKJ5T7N4AQ5W9M2V0E",
      "content": "Do not reveal private details from therapeutic conversations in outgoing feedback letters.",
      "weight": "mandatory",
      "targetLayerKey": "drives"
    }
  ],
  "timestamp": "2026-02-26T02:10:00Z",
  "principalSignature": "986e7d01f64930a8f0a4c238b58314f019f1a84f8eb466f98f44fe1899b848fa0fe4e828a80900f7ee6625f3ce35f3277f4cae73e9d58126a08fd8f160db4a08"
}

20.5 GuidelineResponse Example

{
  "protocolVersion": "0.1.0",
  "guidelineId": "guide_01J0D5A80PE9WRM5A0Y7W3H1JT",
  "snapshotId": "snapshot:therapy-2026q1",
  "responses": [
    {
      "directiveId": "dir_01J0D5CQQX2NB4H3B8ZYX5R9X4",
      "decision": "accept",
      "reasoning": "This improves emotional safety and aligns with observed outcomes."
    },
    {
      "directiveId": "dir_01J0D5DTRKJ5T7N4AQ5W9M2V0E",
      "decision": "accept",
      "reasoning": "Already consistent with current privacy policy; enforcing explicitly is low-risk."
    }
  ],
  "timestamp": "2026-02-26T02:15:00Z",
  "engineSignature": "d5fdd3672aefc423ebf070512dd50445f58a77f5643381fac65a64b0a27983f132f58d9b15ef472046f02d43c888f18499f59f6f8f0f8181afdd6dfe8ca0f503"
}