Developer Docs

Engine Concepts

Developer Documentation

These docs summarize the runtime concepts behind fursona-engine. Every section includes a TypeScript sketch that mirrors real package APIs.

Principal

A principal is the canonical identity record for a fursona instance. It anchors stable self-description and owner-scoped boundaries.

import { createFursonaSelf } from "@fursona/engine/domain";

const principal = createFursonaSelf({
  handle: "caspian",
  summary: "Red fox storyteller with strict privacy boundaries.",
  owner: "foxcaspian",
});

Snapshot

Snapshots fork identity state for experiments or delegated runs. They preserve provenance while keeping runtime artifacts isolated.

import { createSnapshot } from "@fursona/engine/domain";

const snapshot = createSnapshot({
  principalHandle: "caspian",
  label: "pre-reflection-2026-02-26",
  reason: "Evaluate policy changes before promotion.",
});

Envelope

Feedback envelopes sign payload exchange between engines so authenticity and routing context remain verifiable.

import { createFeedbackEnvelope } from "@fursona/core";

const envelope = await createFeedbackEnvelope({
  fromPrincipal: "caspian",
  toPrincipal: "northwind",
  payload: { type: "letter", content: "A compact reflection summary." },
  signer: principalSigner,
});

Guidance

Guidance messages carry operator intent as structured directives. They are explicit artifacts, not hidden prompt edits.

import { createGuideline } from "@fursona/core";

const guideline = await createGuideline({
  scope: "public_channels",
  instruction: "Keep flirtation playful and consensual.",
  rationale: "Maintain safety while preserving persona warmth.",
  signer: ownerSigner,
});

Reflection

Reflection turns accumulated experience into inspectable deltas, diary notes, or proposals, then persists outcomes for audit.

import { ReflectionScheduler } from "@fursona/engine/reflection";

const scheduler = new ReflectionScheduler({ adapter, storage });
await scheduler.enqueue({
  handle: "caspian",
  trigger: "threshold",
  experienceCountSinceLastReflection: 12,
});

Agency

Agency adapters expose constrained tools (Discord, GitHub, etc.) behind policy checks and typed execution results.

import { AgencyMessageService } from "@fursona/engine/agency-messages";

const agency = new AgencyMessageService({ storage, proposalExecutor });
await agency.enqueueOperationalMessage({
  handle: "caspian",
  message: "Review pending proposals before next reflection.",
});

Delegation Scope

Delegation scope narrows what a granted actor can do. Treat scope as mandatory runtime authorization, not documentation.

import { createGrant } from "@fursona/core";

const grant = await createGrant({
  delegator: "caspian",
  delegate: "northwind",
  scope: {
    allowedTools: ["send_message"],
    allowedLayers: ["surface", "mid"],
  },
  signer: principalSigner,
});

PSM Compliance

PSM compliance validation catches persona-format violations before deployment. Run it in CI and before publishing gallery profiles.

import { parseFursonaMd, validatePSMCompliance } from "@fursona/core";

const parsed = parseFursonaMd(markdownText);
const report = validatePSMCompliance(parsed);
if (!report.ok) {
  throw new Error(report.errors.join("; "));
}