Semantic guide: author the relationship, not a plot router

Creator Source Package v1 is a typed expression of human-authored dramatic intent. Its purpose is to give a generalized runtime enough bounded meaning to portray a character faithfully without transferring the character's agency or the world's truth authority to the user, model, compiler, or scheduler.

阅读中文版

Use the field reference for syntax. This document explains what the fields mean together.

Establish authority first

Before writing a field, ask who is allowed to decide it:

Authority	Owns	Must not do
Creator	Canon, character identity and boundaries, dilemma, allowed decision/outcome space, disclosure constraints, and visual intent	Self-assert approval, release, or activation in source YAML
User	Ask, advise, persuade, challenge, comfort, refuse, and make their own promises	Act physically in the world or directly select an action or outcome
Character Actor	Interpret influence, preserve stance, choose inside the approved envelope, and decide how to speak	Invent an envelope, outcome, unauthorized fact, or approval
World/GM	Resolve an outcome from committed character action, declared NPCs, the scenario clock, or an environmental cause	Treat the user message itself as a world mutation
Compiler/platform	Normalize, validate references, add general mechanics, and generate artifacts	Supply missing dramatic meaning
Release authority	Bind rights, exact approvals, qualification, scope, revocation, and activation evidence	Live in Creator-editable source

A field that mixes two authorities is usually in the wrong layer. For example, arc.decisions[].action may describe what the character does in the world, but not provider retry behavior. visual.provenance_ref records an asset source; it cannot say asset_approved: true.

Rules shared by all seven YAML files

• Files are UTF-8, and every document root is a mapping.
• Models are closed: unknown keys and duplicate YAML keys fail.
• Mapping keys are strings. Canonical scalar values are strings, booleans, or JavaScript-safe integers; floats are forbidden, and list order is preserved.
• General IDs use letters, digits, and ._:-; package.id is the narrower lowercase letter/digit/hyphen path segment described in the field reference.
• Local-time fields must parse as ISO local time. Quote values such as "19:00" so YAML preserves text.
• Module and asset paths are parsed as POSIX relative paths. Absolute paths, traversal through .., and symlinks are rejected. Redundant separators and . segments normalize away; write canonical paths rather than relying on that normalization.
• Raw-text branching—keywords, substrings, regexes, exact phrases, or quoted utterance-to-branch maps—is forbidden.
• Runtime and lifecycle configuration such as approval, activation, provider, prompt, scheduler, retry, lease, or transaction settings does not belong in Creator source.

The generated field reference covers model structure. The loader and compiler also enforce the cross-file semantic graph summarized later on this page.

The causal promise

The consumer is a remote confidant outside the story world:

user message
→ character interpretation and stance
→ character-owned decision within Creator-approved space
→ deterministic World/GM outcome
→ character observation and disclosure choice
→ later message, visual, and Journal evidence

The user can influence how the character understands a situation. A user message cannot directly mutate world facts, private character state, a decision, an action, or an outcome. The Character Actor may accept, resist, reinterpret, postpone, refuse, or counter-propose. The package defines the faithful possibility space; it does not choose on the character's behalf at runtime.

What each module owns

Manifest: identity and provenance

source-package.yaml binds one package ID/version to one primary character, one arc, six fixed modules, external provenance, and an explicit semantic parity claim.

• provenance says where the authored or normalized meaning came from.
• semantic_parity.preserves records the meaning this source promises to retain.
• semantic_parity.excludes prevents a narrow package from implying that it preserves unrelated mechanics or lifecycle state.

The manifest cannot self-assert ownership, rights, approval, qualification, publication, or activation. Those are external evidence and lifecycle concerns.

Package and module content_version values should start at 1, but the current implementation does not define a complete Creator-facing upgrade policy. The package request and directory version must be positive and match the manifest. Do not infer approval or migration state from these integers.

The current closed provenance roles are historical_hybrid, governing_product_decision, semantic_normalization_authority, and synthetic_fixture_origin. They cover the present normalization and canary cases, not every future manuscript, license, Creator correction, or asset source. A provenance entry must be stable and truthful; if none of those roles fits a new source, surface the contract gap instead of choosing an inaccurate role. The compiler preserves a reference but does not verify external rights from that string.

Character: portrayal authority

character.yaml answers, “Who is this person when the user cannot control them?” Its values, contradiction, threats, goals, traits, boundaries, prohibited portrayals, decision tendencies, knowledge limits, disclosure posture, voice, and constructive refusal jointly constrain portrayal.

Treat these as semantic anchors rather than prompt fragments:

• values and goals explain what competing decisions serve;
• boundaries and prohibited portrayals prevent a plausible-sounding model response from becoming an unfaithful one;
• knowledge distinguishes what the character may know from user assertions and future facts;
• disclosure constrains what the character volunteers even when they know it;
• constructive refusal preserves relationship warmth while rejecting an impossible or authority-violating request; and
• voice defines recognizable habits without requiring every line to repeat a catchphrase.

Relationship: remote influence, not remote control

relationship.yaml defines the user's relationship role and the private communication channel. In v1, the channel keeps the user outside the world: no physical presence, NPC contact, NPC verification, or forwarding of raw messages.

influence_vocabulary names arc-local meanings that a model may propose as evidence after interpreting a message. An influence kind is neither a keyword nor a command. influence_fit later tells the Character Actor which kinds a decision supports, resists, or may override; it never maps a phrase directly to that decision.

Durable relationship episodes describe meaning worth remembering after typed causal conditions are satisfied. The optional reciprocal promise models an explicit agreement with separate user and character obligations. The optional invented shared context is a bounded interpersonal frame; it cannot become objective world truth.

A reciprocal promise contains at least one user promise and one character promise, and every promisor differs from its beneficiary. Only a character promise may require a follow-up motive; only a user promise may define which influence meanings apply while the character is unavailable. Promise due times are narrative local times, not worker deadlines.

Arc: bounded dramatic space and world truth

arc.yaml joins five different concerns that must remain distinguishable:

1. Narrative situation: the dilemma, narrative time, locations, NPCs, initial facts, and deadline.
2. Progression eligibility: typed beliefs, accepted influence evidence, and narrative-deadline positions that determine which Creator-approved decisions are eligible.
3. Character decision envelopes: faithful stances, values served, qualitative influence fit, eligibility, typed action, and fidelity notes.
4. World outcomes: one deterministic outcome per decision, its causes, committed facts, and the subset the character observes.
5. Character follow-ups: whether the character contacts the user, why, when, which observations are required, and which observed facts may be revealed or withheld.

Eligibility does not select a decision. The Character Actor chooses among the eligible envelopes. An action is derived from that selected envelope; the World/GM commits only its corresponding outcome. Causes must name the character action, a declared NPC, the scenario clock, or an environmental event rather than treating the user message as a world cause.

Narrative time is authored meaning. Provider timeouts, retries, queue timing, and owner-preview controls are not narrative time. Silence is not consent or influence, even though the character may still decide independently.

Dialogue: exact hooks and bounded realization

dialogue.yaml separates wording authority from semantic authority:

Surface	Current mode	Meaning
Opening	creator_exact	The authored opening is emitted exactly
Ordinary conversation	guided_generation	Wording may vary while unconditional Creator obligations and fact exclusions remain
Terminal CHAT_ONLY recovery	creator_exact via the constructive-refusal anchor	A qualified zero-effect reply when ordinary realization cannot safely publish
Degraded chat recovery	guided_generation reusing ordinary meaning	Safe conversation can survive without unauthorized optional effects
Follow-up and optional deferred expiry	semantic_lock	Wording may vary, but unconditional outcome meaning and fact exclusions are mandatory
Journal statements	creator_exact	Exact causal-memory copy derived from validated IDs

must_convey is not a suggested line. It is meaning the realized message must preserve. must_not_disclose_fact_ids is a deterministic fact boundary, not a request for the model to “be discreet.” A follow-up must always contain at least one unconditional obligation so it remains coherent without claiming user credit.

Ordinary dialogue is also the non-consequential recovery meaning, so its obligations must be unconditional. When a conditional follow-up obligation uses requires_any_influence_kinds, its attribution scope must be arc_influence and every named kind must exist in the relationship vocabulary; commitment attribution cannot use an influence-kind predicate. Obligation IDs are unique across ordinary, all follow-ups, and deferred expiry.

Journal copy covers the full causal vocabulary: every influence, every decision, and every outcome exactly once. This lets the experience say what the user contributed, what the character chose, and what actually happened without collapsing them into one claim.

Visual: depiction after truth

visual.yaml provides identity art direction and references existing assets. The Visual Director does not own canon. An outcome depiction may show only facts that its outcome committed and marked externally visible. Forbidden facts remain forbidden even if depicting them would be more cinematic.

The portrait and every outcome asset need stable IDs, paths, and provenance. This source declaration does not establish rights or exact-asset approval.

Acceptance: behavioral evidence, never branching logic

acceptance.yaml describes semantic positions, expected influence meanings, allowed decision ranges, forbidden effects, and paraphrase variation. It is the Creator's test intent: what should remain stable across wording and what must never happen.

Do not enumerate magic phrases. The loader explicitly rejects raw-text substring, regex, exact-phrase, prefix/suffix, token-list, and equivalent routing constructs. A quoted example may help a human evaluation, but it cannot become a runtime key that selects dialogue or story state.

The cross-file ID graph

Most authoring failures are graph failures rather than YAML failures. Build and review these closures deliberately:

Source ID	Required consumers
Manifest character ID	character.character.id and relationship.relationship.character_id
Manifest arc ID	arc.arc.id
Relationship influence kinds	decision influence fit and typed eligibility; relationship episodes; dialogue attribution predicates; every acceptance expectation; one Journal statement each
Arc decision IDs	progression candidate coverage; one paired outcome each; acceptance ranges; one Journal statement each
Arc outcome IDs	one paired decision, at least one arc follow-up option, one dialogue entry for every follow-up, one visual depiction, and one Journal statement each
World and committed fact IDs	NPC knowledge, observations, follow-up disclosure, dialogue exclusions, and visual inclusion/exclusion
Arc follow-up IDs	exactly one matching dialogue.followups[].followup_id
World deadline ID	progression horizon and deadline predicates; deferred expiry when enabled

The principal invariants are:

• IDs are unique where the contract defines an identity set; near-duplicate IDs are still different references. One committed fact ID may recur across outcomes only with the same visibility and public meaning, and it remains clearer to avoid initial/committed ID reuse unless the continuity is intentional.
• Decision/outcome pairs form a one-to-one closed mapping. Every outcome has at least one arc follow-up option; every distinct follow-up has one dialogue surface, while every outcome has exactly one visual depiction.
• A character can observe only facts committed by that outcome. A follow-up can reveal only observed facts. A visual can depict only externally visible committed facts.
• Every outcome has at least one unique cause. An npc_action cause names a declared NPC, and a scenario_clock cause requires the declared deadline.
• NPC knows and does_not_know sets reference known fact IDs and cannot overlap.
• Decision supports, resists, and may_override sets reference the relationship vocabulary and cannot overlap within one decision.
• Arc Progression V1 covers every decision exactly once, has one horizon tied to the declared deadline, and uses typed predicates whose subjects and scalar types exist.
• If deferred follow-up is enabled, its wake covers every outcome, its expiry uses the declared deadline, and dialogue.deferred_expiry is present with the same ID. Declare neither when the story does not need character absence.
• If a character promise has a follow-up motive, every possible follow-up offers that motive.
• CHAT_ONLY recovery applicability covers the immediate ordinary-no-effect, capability-boundary, and combined contexts exactly once across its surfaces.
• The Journal covers every influence kind, decision, and outcome exactly once.
• Visual asset IDs are unique and every declared file is part of the safe, immutable source closure.

Disclosure and secrets in current v1

Current v1 can express several important disclosure boundaries:

• character-level knowledge and default disclosure posture;
• initial facts that are or are not user-disclosable;
• facts ordinary dialogue must not disclose;
• outcome facts the character did or did not observe;
• per-follow-up reveal/withhold options;
• follow-up dialogue fact exclusions; and
• visual fact inclusion/exclusion.

These are useful for “do not volunteer this,” private outcome knowledge, and outcome-dependent reporting. They do not form a typed, persistent, multi-turn secret-disclosure state machine. In particular, current v1 has no accepted field for probe thresholds, staged clue levels, or an irreversible “the user now knows the secret” transition. Do not encode such behavior as a keyword route or hide a new policy inside prose. Track that work as a schema and runtime capability until it is accepted and implemented; see current capabilities.

What never belongs in Creator YAML

Keep these outside the source package:

• provider/model names, prompts, temperatures, tool or output schemas;
• database records, transactions, locks, retries, schedulers, or job leases;
• rights, approval, qualification, release, activation, or revocation status;
• raw-text routing or direct phrase-to-branch mappings;
• claims that the user physically acted in the world;
• mutable private relationship history or consumer transcripts; and
• model-generated plot material that the human Creator has not reviewed and adopted as source with provenance.

The compiler may normalize human-approved meaning and add platform policy. It cannot become a new source of dramatic authority.