From 909d9be11906de495e21a2b7593373fe24f45f4f Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Fri, 1 May 2026 23:52:15 +0100 Subject: [PATCH] Adopt Ink for branching scenes --- docs/architecture/ink-branching-scenes.md | 100 +++++++++ docs/architecture/sequential-agent-runtime.md | 23 ++- examples/ink/cold-wake-sanctuary-intake.ink | 148 ++++++++++++++ .../cold-wake-sanctuary-intake.training.json | 189 +++++++++++++++++ notes/fresh-workspace-handoff.md | 30 ++- notes/ghostlight-current-system-map.md | 24 ++- notes/ghostlight-implementation-plan.md | 14 +- package-lock.json | 25 +++ package.json | 8 +- state/evidence.jsonl | 1 + state/map.yaml | 6 +- tools/validate_ink_examples.py | 193 ++++++++++++++++++ 12 files changed, 732 insertions(+), 29 deletions(-) create mode 100644 docs/architecture/ink-branching-scenes.md create mode 100644 examples/ink/cold-wake-sanctuary-intake.ink create mode 100644 examples/ink/cold-wake-sanctuary-intake.training.json create mode 100644 package-lock.json create mode 100644 tools/validate_ink_examples.py diff --git a/docs/architecture/ink-branching-scenes.md b/docs/architecture/ink-branching-scenes.md new file mode 100644 index 0000000..face8b6 --- /dev/null +++ b/docs/architecture/ink-branching-scenes.md @@ -0,0 +1,100 @@ +# Ink Branching Scenes + +Ink is the branching scene format. + +Ghostlight should not invent a parallel dialogue-tree language unless Ink +fails a concrete requirement. Ink already gives us readable interactive fiction, +choices, knots, stitches, variables, tags, compiled JSON, and a format writers +can inspect without needing to wear a compiler helmet indoors. + +Ghostlight's job is the machinery around Ink: + +- build actor-local awareness from agent state and scene state +- project plausible speech and non-speech choices +- annotate why those choices make sense +- preserve listener interpretation as separate from actor intent +- record consequence surfaces for later state mutation +- keep fuzzy social updates reviewed until there is training data +- compile Ink into game-consumable JSON + +Ink owns the playable branch structure. Ghostlight owns the psychological, +cultural, memory, relationship, and consequence rationale. + +## Runtime Shape + +The near-term authoring path is: + +```text +agent state + scene state + lore grounding + -> local awareness + -> projected branch choices and NPC responses + -> Ink scene + -> compiled Ink JSON + -> reviewed training annotations + -> selected branch consequences + -> state, memory, belief, and relationship updates +``` + +The Ink file should be readable as Aetheria content on its own. The sidecar +training annotation should explain which Ghostlight state produced each branch +and which consequences are automatic, reviewed, or deferred. + +## Ink Tags + +Use Ink tags for lightweight traceability: + +- `ghostlight.scene` +- `ghostlight.fixture` +- `ghostlight.branch` +- `ghostlight.action` +- `ghostlight.intent` +- `ghostlight.npc_response` +- `ghostlight.consequence` +- `ghostlight.training_hook` +- `aetheria.flashpoint` + +Tags are not the full state model. They are handles that let runtime and +training tools connect a playable branch back to Ghostlight state. + +## Sidecar Annotations + +Each Ink scene should have a `.training.json` sidecar with: + +- source fixture reference +- protagonist and NPC ids +- actor-local awareness summary +- projection controls +- branch ids and Ink knot paths +- action type and actor intent +- state basis +- reviewed consequences +- training hooks +- mutation policy + +This sidecar is intentionally not a new branching format. It is a receipt. Ink +remains the scene tree; the sidecar says why the tree grew that way and which +state changes a reviewer accepted. + +## Mutation Policy + +Ink variables can record local playthrough outcomes. They should not silently +become canonical Ghostlight state. + +Automatic: + +- Ink compilation +- branch id and knot validation +- local variables for the current playthrough +- mechanical tags and training hook checks + +Manual reviewed until trained: + +- relationship deltas +- belief updates +- memory writes +- listener misread classification +- activation changes +- promotion from branch outcome into durable Aetheria lore + +The first prototype lives in +`examples/ink/cold-wake-sanctuary-intake.ink`. diff --git a/docs/architecture/sequential-agent-runtime.md b/docs/architecture/sequential-agent-runtime.md index 5860a5f..7155225 100644 --- a/docs/architecture/sequential-agent-runtime.md +++ b/docs/architecture/sequential-agent-runtime.md @@ -8,6 +8,10 @@ use, refusal, revelation, concealment, violence, withdrawal, trade, or any other scene-valid action. "Dialogue tree" does not mean a tree made only of spoken lines. It means an interactive branch structure for a character encounter. +Ink is the branch format for that structure. Ghostlight should not invent its +own dialogue-tree file format while Ink already exists and fits the job. See +`docs/architecture/ink-branching-scenes.md` for the integration contract. + Ghostlight should set up a scene, generate plausible things the protagonist or NPCs could do, generate responses from the people present, and propagate the consequences into world state, memory, belief, and social perception. @@ -46,7 +50,9 @@ withdrawal, refusal, or concession. That is the point of the machine. For game use, the loop should be able to emit: - a scene transcript -- candidate player choices, including speech and non-speech actions +- Ink scenes with candidate player choices, including speech and non-speech + actions +- compiled Ink JSON - NPC response branches - state/memory/social-perception deltas for each branch - unresolved hooks for later scenes @@ -320,18 +326,19 @@ agent state + scene state The next implementation should not try to simulate a city. Calm down, wizard. -Prototype one tiny branching-scene loop: +Prototype one tiny Ink-backed branching scene loop: 1. Load `examples/agent-state.cold-wake-story-lab.json`. 2. Select one scene and one acting agent. 3. Build a local awareness packet from existing state. 4. Compile projection controls. -5. Render a prompt that asks for an action or dialogue response. -6. Send it to Qwen. -7. Save the response as an event proposal. -8. Apply a small deterministic mutation: - - append event - - apply only mechanical world/resource/object deltas the resolver can prove +5. Generate or author an Ink scene with branch choices and NPC responses. +6. Compile the Ink scene to JSON with `inkjs`. +7. Save a sidecar training annotation that maps Ink branches to Ghostlight + state basis, actor intent, consequence surfaces, and mutation policy. +8. Apply selected branch consequences only through reviewed mutation: + - Ink variables can track local playthrough facts + - canonical state changes require resolver/reviewer approval 9. Manually review fuzzy state effects: - add one memory or belief update - adjust one or two `current_activation` values diff --git a/examples/ink/cold-wake-sanctuary-intake.ink b/examples/ink/cold-wake-sanctuary-intake.ink new file mode 100644 index 0000000..949b0dd --- /dev/null +++ b/examples/ink/cold-wake-sanctuary-intake.ink @@ -0,0 +1,148 @@ +VAR sella_trust = 57 +VAR sella_obligation = 48 +VAR maer_obligation = 60 +VAR bay_reserved = false +VAR packet_shown = false + +=== start === +# ghostlight.scene: scene-02-sanctuary-intake +# ghostlight.fixture: examples/agent-state.cold-wake-story-lab.json +# aetheria.flashpoint: cold-wake-panic + +The intake clinic sits behind the pumpworks where the dockside heat exchangers +make every prayer sound like a maintenance complaint. + +Sella Ren has three names on the red board, eight on orange, and one empty +monitored bay that exists mostly as an argument people keep trying to win. + +Maer Tidecall stands in the doorway with the corrupted packet on his slate. The +packet might be medical telemetry, firmware noise, testimony, or a cruel little +mess of all three. + +Sella does not look at the slate first. She looks at Maer. + +"If you came to ask me for mercy," she says, "bring tubing." + +What does Maer do? + +* [Name the cost and put the route ledger behind it.] + # ghostlight.branch: branch-maer-name-cost-and-offer-ledger + # ghostlight.action: speak + # ghostlight.intent: ask_for_capacity_while_accepting_material_obligation + -> ledger_backed_bay + +* [Step to the intake board and help triage before asking.] + # ghostlight.branch: branch-maer-help-triage-before-asking + # ghostlight.action: gesture + # ghostlight.intent: earn_the_right_to_ask_by_sharing_logistical_burden + -> triage_first + +* [Show Sella the corrupted packet.] + # ghostlight.branch: branch-maer-show-packet + # ghostlight.action: show_object + # ghostlight.intent: make_uncertainty_morally_present_without_overclaiming + -> show_packet + +* [Press the personhood risk until capacity stops being the only frame.] + # ghostlight.branch: branch-maer-press-moral-frame + # ghostlight.action: speak + # ghostlight.intent: force_personhood_risk_to_dominate_capacity_limits + -> moral_pressure + +=== ledger_backed_bay === +~ bay_reserved = true +~ sella_trust = 61 +~ sella_obligation = 53 +~ maer_obligation = 66 + +Maer keeps his hands away from the empty bay's control rail. + +"One monitored bay," he says. "Not charity. Put the oxygen, cold-chain, and +staff hours on my route ledger until the tribunal learns what courage costs." + +Sella's face does not soften. That would be too cheap, and she has never liked +cheap things pretending to be mercy. + +She marks the bay conditional in amber. + +"One bay," she says. "Witnessed, conditional, and revocable if that packet turns +into contagion math. Your ledger buys time, Maer. Not absolution." + +The clinic exhales around them, annoyed to discover it is still alive. + +# ghostlight.npc_response: sella_conditional_acceptance +# ghostlight.consequence: conditional_bay_reserved +# ghostlight.training_hook: care_as_capacity +# ghostlight.training_hook: obligation_backed_request +-> END + +=== triage_first === +~ sella_trust = 60 + +Maer lowers the slate and steps to the intake wall. + +He does not touch the red cases. He reads orange tags, finds the two whose +timers are lying politely, and moves neither until Sella gives the smallest +possible nod. + +"If I ask," he says, "I should know what I am asking you to steal from." + +Sella hands him a marker. + +"Orange only," she says. "Touch red without asking and I will make the Compact +explain your hands in writing." + +It is not permission. It is worse. It is work. + +# ghostlight.npc_response: sella_conditional_delegation +# ghostlight.consequence: trust_test_opened +# ghostlight.training_hook: authority_respecting_help +-> END + +=== show_packet === +~ packet_shown = true + +Maer turns the slate so Sella can see the packet's broken rhythm. + +He does not say person. He does not say cargo. He lets the little damaged +pattern fail to be either. + +Sella watches too long for someone who wants this to be simple. + +"That is not proof," she says. + +"No." + +"It is enough to make me hate the word cargo." + +Her thumb hovers over the isolation protocol. Not over the bay. + +"You brought me a worse problem, which is very Navigator of you." + +# ghostlight.npc_response: sella_protocol_before_mercy +# ghostlight.consequence: packet_seen_no_personhood_resolution +# ghostlight.training_hook: unresolved_evidence_pressure +-> END + +=== moral_pressure === +~ sella_trust = 52 + +Maer lets the packet stay dark. + +"If we wait for proof clean enough to satisfy the freeze," he says, "we may be +helping them rename a person as debris." + +The drawer under Sella's hand closes. + +Not hard. Hard would have been kinder. + +"Do not spend my dead to make your sentence cleaner, Maer. Bring me capacity or +bring me quiet." + +For a moment the only thing between them is the board, which has been keeping +score longer than either of them has been brave. + +# ghostlight.npc_response: sella_rejects_symbolic_pressure +# ghostlight.consequence: trust_loss_resentment_risk +# ghostlight.training_hook: moral_pressure_as_resource_substitution +-> END diff --git a/examples/ink/cold-wake-sanctuary-intake.training.json b/examples/ink/cold-wake-sanctuary-intake.training.json new file mode 100644 index 0000000..30e672f --- /dev/null +++ b/examples/ink/cold-wake-sanctuary-intake.training.json @@ -0,0 +1,189 @@ +{ + "schema_version": "ghostlight.ink_training_annotation.v0", + "annotation_id": "cold-wake-sanctuary-intake-training-v0", + "ink_ref": "examples/ink/cold-wake-sanctuary-intake.ink", + "source_fixture_ref": "examples/agent-state.cold-wake-story-lab.json", + "scene_id": "scene-02-sanctuary-intake", + "protagonist_agent_id": "maer_tidecall", + "npc_agent_ids": [ + "sella_ren" + ], + "purpose": "Use Ink as the playable branching fiction surface while preserving Ghostlight state, projection, and consequence rationale as reviewed training data.", + "local_awareness_summary": [ + { + "text": "Maer knows the clinic is nearly full, the packet may be testimony or noise, and rescue becomes theater if no one prepares intake.", + "source_refs": [ + "scenes.scene-02-sanctuary-intake.dialogue_context_packs.maer_tidecall.speaker_local_truth" + ] + }, + { + "text": "Maer believes Sella will not hide behind false capacity, but asking her for help may be necessary and unfair.", + "source_refs": [ + "scenes.scene-02-sanctuary-intake.dialogue_context_packs.maer_tidecall.speaker_beliefs" + ] + }, + { + "text": "Sella treats care as beds, food, air, consent, repair, and ongoing work rather than sentimental intent.", + "source_refs": [ + "agents.sella_ren.memories.memory-care-is-capacity" + ] + } + ], + "projection_controls": { + "frame_controls": [ + { + "text": "Frame the scene as capacity negotiation under uncertainty, not a morality duel with a clean answer.", + "source_refs": [ + "scenes.scene-02-sanctuary-intake.public_stakes", + "scenes.scene-02-sanctuary-intake.hidden_stakes" + ] + } + ], + "authority_boundaries": [ + { + "text": "Maer can ask, offer ledger backing, show or withhold the packet, and incur obligation; Sella controls sanctuary intake.", + "source_refs": [ + "scenes.scene-02-sanctuary-intake.dialogue_context_packs", + "agents.sella_ren.goals.goal-keep-sanctuary-open" + ] + } + ], + "object_custody": [ + { + "text": "The corrupted packet can be shown, withheld, or summarized, but it cannot be treated as clean proof.", + "source_refs": [ + "scenes.scene-02-sanctuary-intake.public_stakes", + "scenes.scene-02-sanctuary-intake.hidden_stakes" + ] + } + ], + "required_semantics": [ + { + "text": "Care must remain logistics and obligation, not just compassion.", + "source_refs": [ + "agents.sella_ren.memories.memory-care-is-capacity" + ] + } + ], + "forbidden_resolutions": [ + { + "text": "Do not resolve whether the packet contains a person.", + "source_refs": [ + "scenes.scene-02-sanctuary-intake.hidden_stakes" + ] + }, + { + "text": "Do not make Sella accept without cost, condition, or resentment risk.", + "source_refs": [ + "relationships.rel-sella-maer.summary" + ] + } + ] + }, + "branches": [ + { + "branch_id": "branch-maer-name-cost-and-offer-ledger", + "ink_path": "ledger_backed_bay", + "action_type": "speak", + "actor_intent": "ask_for_capacity_while_accepting_material_obligation", + "state_basis": [ + "Maer values rescue before category.", + "Maer believes Sella will not hide behind false capacity.", + "Sella's care model responds to material support better than moral pressure." + ], + "reviewed_consequences": [ + "One monitored bay is conditionally reserved.", + "Maer incurs route-ledger obligation.", + "Sella's active trust and obligation toward Maer rise slightly under manual review." + ], + "training_hooks": [ + "care_as_capacity", + "obligation_backed_request", + "consumer_behavior_cost_acceptance" + ] + }, + { + "branch_id": "branch-maer-help-triage-before-asking", + "ink_path": "triage_first", + "action_type": "gesture", + "actor_intent": "earn_the_right_to_ask_by_sharing_logistical_burden", + "state_basis": [ + "Maer recognizes that the ask is unfair.", + "Sella respects useful work more than symbolic care." + ], + "reviewed_consequences": [ + "Sella allows bounded help while defending triage authority.", + "Trust may rise if Maer respects red-list boundaries." + ], + "training_hooks": [ + "authority_respecting_help", + "iterated_trust_test" + ] + }, + { + "branch_id": "branch-maer-show-packet", + "ink_path": "show_packet", + "action_type": "show_object", + "actor_intent": "make_uncertainty_morally_present_without_overclaiming", + "state_basis": [ + "The packet may be testimony or noise.", + "Sella suspects personhood but cannot prove it." + ], + "reviewed_consequences": [ + "Sella sees stronger unresolved evidence.", + "Isolation protocol pressure rises before bay commitment." + ], + "training_hooks": [ + "unresolved_evidence_pressure", + "information_exposure_without_resolution" + ] + }, + { + "branch_id": "branch-maer-press-moral-frame", + "ink_path": "moral_pressure", + "action_type": "speak", + "actor_intent": "force_personhood_risk_to_dominate_capacity_limits", + "state_basis": [ + "Maer's grievance activation and suspicion are elevated.", + "The packet's possible personhood makes pure capacity accounting feel morally obscene to Maer." + ], + "reviewed_consequences": [ + "Sella rejects moral pressure as a substitute for capacity.", + "Sella's active trust in Maer drops under manual review." + ], + "training_hooks": [ + "moral_pressure_as_resource_substitution", + "trust_loss_from_symbolic_cost_transfer" + ] + } + ], + "mutation_policy": { + "automated": [ + "Ink variables may record local branch outcomes for playthrough state.", + "Compiled Ink JSON can be consumed by runtime tools." + ], + "manual_review_required": [ + "Relationship deltas", + "Belief updates", + "Memory writes", + "Listener misread classification", + "Promotion from branch outcome into canonical Aetheria lore" + ] + }, + "audit": { + "reviewer": "Codex", + "review_status": "accepted", + "review_notes": [ + "Ink owns branching structure; Ghostlight owns state rationale and consequence annotation.", + "Branches include speech, gesture, and object revelation.", + "The scene preserves future hooks for economic/resource behavior without implementing an economy loop." + ], + "checks": { + "uses_standard_branching_format": true, + "actor_local_context_only": true, + "includes_non_speech_actions": true, + "fuzzy_updates_marked_for_manual_review": true, + "aetheria_lore_content_readable": true + } + } +} diff --git a/notes/fresh-workspace-handoff.md b/notes/fresh-workspace-handoff.md index 6b35fcf..4068bc3 100644 --- a/notes/fresh-workspace-handoff.md +++ b/notes/fresh-workspace-handoff.md @@ -39,6 +39,7 @@ Ghostlight now has the persistence spine plus the first architecture payload: - `docs/architecture/prompt-projection-contract.md` - `docs/architecture/projection-distillation-plan.md` - `docs/architecture/sequential-agent-runtime.md` + - `docs/architecture/ink-branching-scenes.md` - evaluation follow-up docs: - `docs/architecture/schema-future-mechanisms.md` - Aetheria lore grounding docs: @@ -63,6 +64,11 @@ Ghostlight now has the persistence spine plus the first architecture payload: - `tools/build_cold_wake_story_lab_fixture.py` - `tools/run_qwen_projection.py` - `tools/validate_qwen_captures.py` +- Ink branching seam: + - `examples/ink/cold-wake-sanctuary-intake.ink` + - `examples/ink/cold-wake-sanctuary-intake.training.json` + - `tools/validate_ink_examples.py` + - `inkjs` dev dependency and `npm run ink:validate` - Cold Wake fixture note: - `docs/architecture/aetheria-cold-wake-training-fixture.md` - first projection example seam: @@ -73,8 +79,9 @@ Ghostlight now has the persistence spine plus the first architecture payload: - visitor-facing README refreshed to explain Ghostlight's goals There is still no full runtime yet. The live machine is design, state -discipline, a cleaner repo boundary, the first executable state contract, and a -documented projection path. +discipline, a cleaner repo boundary, the first executable state contract, a +documented projection path, and the first Ink-backed playable branching scene +with reviewed training annotations. ## Current Direction @@ -91,9 +98,10 @@ training feedstock for projection and dialogue scaffolding. ## Current Next Action -Build the first deterministic scene-local dialogue prototype: local awareness, -projection controls, action/dialogue prompt, Qwen event proposal, conservative -state mutation, and validation on one Cold Wake story-lab beat. +Build the next Ink-backed scene prototype pass: generate or project branch +choices from local awareness, compile Ink, validate sidecar training +annotations, and test one selected branch's reviewed state/memory/relationship +mutation. Cat/Oz remains useful as an Elysium procedural mechanics fixture, but grounded training data should start from authored historical lore rather than gameplay @@ -132,14 +140,20 @@ Completed projection path items: `required_semantics`, and `forbidden_resolutions` - add a Qwen projection runner and capture validator so response artifacts are reviewed training receipts, not loose logs +- adopt Ink as the standard playable branching scene format rather than + inventing a parallel Ghostlight dialogue-tree format +- add the first Cold Wake Ink scene, + `examples/ink/cold-wake-sanctuary-intake.ink`, with a reviewed sidecar + annotation tying branches to Ghostlight state, projection controls, + consequence surfaces, and manual mutation policy Remaining projection path: - build a deterministic speaker-local input slicer - build a renderer that emits projection controls before prompt prose -- build the first scene-local branching tick so an agent can act from local - awareness, produce branchable speech or non-speech action, trigger NPC - responses, and mutate only the state it has authority to affect +- build the first local-awareness-to-Ink generation pass so an agent can act + from local awareness, produce branchable speech or non-speech choices, trigger + NPC responses, and annotate mutations without replacing Ink - keep the near-term product target to interactive dialogue trees and scene-local consequences - preserve training-data hooks for future open-world behavior, iterated diff --git a/notes/ghostlight-current-system-map.md b/notes/ghostlight-current-system-map.md index 882872c..509e118 100644 --- a/notes/ghostlight-current-system-map.md +++ b/notes/ghostlight-current-system-map.md @@ -50,6 +50,10 @@ state and re-entry discipline. generated actions become event proposals, and bounded state mutation drives branchable speech or non-speech scene consequences while preserving training hooks for later open-world, economic, and faction decision models +- `docs/architecture/ink-branching-scenes.md` + - integration contract that makes Ink the standard playable branch format + while Ghostlight owns local awareness, projection rationale, consequence + review, and state mutation around Ink scenes - `docs/experiments/cold-wake-story-lab.md` - four-scene Cold Wake writing experiment using Ghostlight projection as a story-generation crutch and training-data source @@ -99,6 +103,13 @@ state and re-entry discipline. - `examples/lore-grounding/cold-wake-panic.ganymede-corridor.json` - first draft historical grounding digest, centered on Cold Wake Panic in the Ganymede/Jovian corridor +- `examples/ink/cold-wake-sanctuary-intake.ink` + - first playable Ink-backed Cold Wake branching scene, using speech, gesture, + object revelation, and moral-pressure branches +- `examples/ink/cold-wake-sanctuary-intake.training.json` + - reviewed sidecar annotation tying Ink branches to Ghostlight local + awareness, projection controls, branch rationale, consequence surfaces, and + manual mutation policy - `tools/ghostlight_state.py` - compact state inspection and evidence or branch updates - `tools/ghostlight_prepare_compaction.py` @@ -114,6 +125,9 @@ state and re-entry discipline. - validates reviewed Qwen response capture receipts - `tools/validate_lore_grounding.py` - dependency-free validator for lore grounding digest examples +- `tools/validate_ink_examples.py` + - compiles Ink examples with `inkjs` and validates sidecar training + annotations - `tools/build_cold_wake_story_lab_fixture.py` - generator for the verbose Cold Wake story-lab state fixture @@ -127,12 +141,14 @@ state and re-entry discipline. - a simulation/event loop implementation - a relationship engine - a culture prior engine +- an automatic Ink branch generator from local awareness +- automatic promotion of Ink branch outcomes into canonical state The canonical agent-state schema, projection example schema, lore grounding digest schema, first draft Cold Wake grounding digest, and first Cold Wake story-lab Qwen captures now exist as v0 seams. The first complete Cold Wake story pass exists with receipts, and projection controls have been promoted as -the architectural answer to repeated prompt leaks. The next implementation -target is the first deterministic scene-local dialogue tick: local awareness, -action/dialogue prompt, event proposal, conservative state mutation, and -validation. +the architectural answer to repeated prompt leaks. Ink is now the standard +branching scene format; the next implementation target is projecting or +generating Ink branches from local awareness and testing selected branch +mutation through reviewed state, memory, and relationship updates. diff --git a/notes/ghostlight-implementation-plan.md b/notes/ghostlight-implementation-plan.md index 2bc4de4..e202504 100644 --- a/notes/ghostlight-implementation-plan.md +++ b/notes/ghostlight-implementation-plan.md @@ -38,6 +38,9 @@ 4. Build the scene-local sequential dialogue loop. New target. - Use `docs/architecture/sequential-agent-runtime.md` as the first runtime contract. + - Use `docs/architecture/ink-branching-scenes.md` as the branch-format + contract. Ink owns playable branching scenes; Ghostlight owns local + awareness, projection rationale, consequences, and reviewed state mutation. - Keep the product target narrow: procedural branching scene trees for games first. "Dialogue tree" means speech and non-speech actions, not only spoken lines. @@ -62,8 +65,8 @@ appraiser training data. - Keep author control at stage-setting and high-level constraints; do not require the author to script every beat. - - Emit game-useful artifacts: scene transcript, candidate player choices, - including non-speech actions, NPC response branches, + - Emit game-useful artifacts: Ink scene source, compiled Ink JSON, scene + transcript, candidate player choices, including non-speech actions, NPC response branches, state/memory/social-perception deltas, and unresolved hooks. - For protagonist scenes, generate several plausible things the protagonist could do from state and affordances, then generate NPC responses and branch @@ -76,9 +79,10 @@ - Still record why agents buy, refuse, trade, hoard, comply, defect, conceal, punish, or help when those decisions appear in scenes; those reviewed decisions are seed data for later consumer-behavior and faction models. - - First prototype: rerun one Cold Wake story-lab beat through a deterministic - local-awareness/projection-control renderer, then apply one conservative - state mutation and validate the resulting fixture. + - First prototype: express one Cold Wake story-lab beat as Ink, compile it, + and validate a sidecar training annotation that maps branches to + Ghostlight state basis, action intent, consequence surfaces, and manual + mutation policy. 5. Build the projection distillation loop. Started. - Use `docs/architecture/projection-distillation-plan.md` as the teacher to diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..38f32c4 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,25 @@ +{ + "name": "ghostlight", + "version": "0.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "ghostlight", + "version": "0.0.0", + "devDependencies": { + "inkjs": "^2.4.0" + } + }, + "node_modules/inkjs": { + "version": "2.4.0", + "resolved": "https://registry.npmjs.org/inkjs/-/inkjs-2.4.0.tgz", + "integrity": "sha512-EoPCYESIbMtfI8SqEDZCJwn+A5is0QozMLw250iic1ReJCgZpRKIezWj0VqgRUzAx0f3MmEbsUjY/ILe2815JQ==", + "dev": true, + "license": "MIT", + "bin": { + "inkjs-compiler": "bin/inkjs-compiler.js" + } + } + } +} diff --git a/package.json b/package.json index 1a93001..ca2abe1 100644 --- a/package.json +++ b/package.json @@ -7,9 +7,13 @@ "state:status": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\ghostlight_state.py status", "state:prepare-compaction": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\ghostlight_prepare_compaction.py", "agent-state:validate": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\validate_agent_state.py", - "schema:validate": "npm run agent-state:validate && npm run projection:validate && npm run lore-grounding:validate && npm run qwen-captures:validate", + "schema:validate": "npm run agent-state:validate && npm run projection:validate && npm run lore-grounding:validate && npm run qwen-captures:validate && npm run ink:validate", "projection:validate": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\validate_projection_examples.py", "lore-grounding:validate": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\validate_lore_grounding.py", - "qwen-captures:validate": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\validate_qwen_captures.py" + "qwen-captures:validate": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\validate_qwen_captures.py", + "ink:validate": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\validate_ink_examples.py" + }, + "devDependencies": { + "inkjs": "^2.4.0" } } diff --git a/state/evidence.jsonl b/state/evidence.jsonl index 2d95760..18114b6 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -33,3 +33,4 @@ {"ts": "2026-05-01T22:31:04+00:00", "type": "design", "status": "accepted", "note": "Tightened Ghostlight runtime scope: near-term goal is procedural interactive dialogue trees and scene-local consequence propagation into state, memory, and social perception. Sequential agent machinery should serve branchable game dialogue first; world-scale simulation, autonomous offscreen factions, economy, and long-horizon plot generation stay deferred."} {"ts": "2026-05-01T22:36:38+00:00", "type": "design", "status": "accepted", "note": "Adjusted scope boundary: implement scene-local interactive dialogue first, but shape training data for later open-world agents, iterated decisions, psychologically grounded consumer behavior, scarcity/reputation pressure, and major faction or institution decision-making. Defer full simulation loops, not the labels and state hooks those future models will need."} {"ts": "2026-05-01T22:40:18+00:00", "type": "design", "status": "accepted", "note": "Clarified that dialogue trees mean branching scene trees, not speech-only menus. Ghostlight should generate plausible protagonist speech or non-speech choices, NPC responses, and branch consequences in world state, memory, and social perception, such as losing trust or opening future hooks."} +{"ts": "2026-05-01T22:51:37+00:00", "type": "design", "status": "accepted", "note": "Adopted Ink as the standard playable branching scene format for Ghostlight interactive fiction. Ghostlight should generate/project Ink scenes and maintain reviewed sidecar annotations for local awareness, action intent, consequence surfaces, and manual state mutation instead of inventing a parallel branching format."} diff --git a/state/map.yaml b/state/map.yaml index 80b4848..e9d6f81 100644 --- a/state/map.yaml +++ b/state/map.yaml @@ -108,7 +108,9 @@ accepted_design: - Scope boundary: implement interactive branching scene trees and scene-local consequences first; dialogue trees include speech and non-speech actions, while preserving training data hooks for open-world contexts, iterated decisions, economic behavior, scarcity, reputation, faction pressure, and institution decision-making. - Do not train dialogue-only models that will be useless for later game-world simulation; reviewed scene data should preserve why agents buy, refuse, trade, hoard, comply, defect, conceal, punish, or help when those decisions appear. - Branching scene generation should propose plausible protagonist choices, including speech, silence, movement, object use, concealment, revelation, withdrawal, violence, trade, or refusal, then record NPC responses and branch consequences such as trust loss or future hooks. + - Ink is the standard branching scene format for playable interactive fiction; Ghostlight should project and annotate Ink scenes rather than inventing a parallel dialogue-tree language. + - Ink sidecar training annotations preserve actor-local awareness, projection controls, branch rationale, action intent, reviewed consequences, and manual mutation policy while keeping Ink itself as the branch structure. current_status: - summary: Ghostlight now has the Epiphany-style persistence spine, the first architecture payload, the v0 canonical agent-state schema seam, prompt projection docs, immediate schema fixes from evaluation, first reviewed Cat/Oz projection examples, a revised Aetheria lore-grounding architecture, a lore grounding digest schema, the first draft Cold Wake historical grounding digest, a Cold Wake story-lab fixture, projection controls, validated Qwen capture receipts, and a complete Cold Wake short story assembled from accepted projection outputs. - next_action: Build the first deterministic scene-local branching prototype: local awareness, projection controls, protagonist speech/action choices, NPC response generation, event proposals, conservative state mutation, and validation on one Cold Wake story-lab beat. + summary: Ghostlight now has the Epiphany-style persistence spine, the first architecture payload, the v0 canonical agent-state schema seam, prompt projection docs, immediate schema fixes from evaluation, first reviewed Cat/Oz projection examples, a revised Aetheria lore-grounding architecture, a lore grounding digest schema, the first draft Cold Wake historical grounding digest, a Cold Wake story-lab fixture, projection controls, validated Qwen capture receipts, a complete Cold Wake short story assembled from accepted projection outputs, and the first Ink-backed Cold Wake branching scene with reviewed training annotations. + next_action: Build the next Ink-backed scene prototype pass: generate or project branch choices from local awareness, compile Ink, validate sidecar training annotations, and test one selected branch's reviewed state/memory/relationship mutation. diff --git a/tools/validate_ink_examples.py b/tools/validate_ink_examples.py new file mode 100644 index 0000000..3978276 --- /dev/null +++ b/tools/validate_ink_examples.py @@ -0,0 +1,193 @@ +"""Validate Ghostlight Ink examples and sidecar training annotations.""" + +from __future__ import annotations + +import argparse +import json +import shutil +import subprocess +import tempfile +from pathlib import Path +from typing import Any + + +ROOT = Path(__file__).resolve().parents[1] +DEFAULT_INK_FILES = sorted((ROOT / "examples" / "ink").glob("*.ink")) +VALID_ACTION_TYPES = { + "speak", + "silence", + "move", + "gesture", + "touch_object", + "block_object", + "use_object", + "show_object", + "withhold_object", + "transfer_object", + "spend_resource", + "attack", + "wait", + "mixed", +} + + +class ValidationError(Exception): + pass + + +def require(condition: bool, message: str) -> None: + if not condition: + raise ValidationError(message) + + +def require_keys(obj: dict[str, Any], keys: list[str], path: str) -> None: + missing = [key for key in keys if key not in obj] + require(not missing, f"{path} missing required keys: {', '.join(missing)}") + + +def load_json(path: Path) -> Any: + return json.loads(path.read_text(encoding="utf-8")) + + +def npx_command() -> str: + command = shutil.which("npx.cmd") or shutil.which("npx") + require(command is not None, "npx is required to compile Ink examples") + return command + + +def compile_ink(path: Path) -> None: + with tempfile.TemporaryDirectory(prefix="ghostlight-ink-") as temp_dir: + output_path = Path(temp_dir) / f"{path.stem}.json" + result = subprocess.run( + [npx_command(), "inkjs-compiler", str(path), "-o", str(output_path)], + cwd=ROOT, + text=True, + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + check=False, + ) + require( + result.returncode == 0, + f"{path} failed Ink compilation\nSTDOUT:\n{result.stdout}\nSTDERR:\n{result.stderr}", + ) + require(output_path.exists(), f"{path} did not produce compiled Ink JSON") + compiled = output_path.read_text(encoding="utf-8-sig") + require(compiled.strip().startswith("{"), f"{path} compiled output is not JSON") + + +def validate_text_blocks(items: Any, path: str) -> None: + require(isinstance(items, list), f"{path} must be an array") + for index, item in enumerate(items): + item_path = f"{path}[{index}]" + require(isinstance(item, dict), f"{item_path} must be an object") + require_keys(item, ["text", "source_refs"], item_path) + require(isinstance(item["text"], str) and item["text"].strip(), f"{item_path}.text must be non-empty") + require(isinstance(item["source_refs"], list) and item["source_refs"], f"{item_path}.source_refs must be non-empty") + + +def validate_annotation(path: Path, ink_path: Path) -> None: + data = load_json(path) + require(isinstance(data, dict), f"{path} must be an object") + require_keys( + data, + [ + "schema_version", + "annotation_id", + "ink_ref", + "source_fixture_ref", + "scene_id", + "protagonist_agent_id", + "npc_agent_ids", + "local_awareness_summary", + "projection_controls", + "branches", + "mutation_policy", + "audit", + ], + str(path), + ) + require(data["schema_version"] == "ghostlight.ink_training_annotation.v0", f"{path}.schema_version is wrong") + require((ROOT / data["ink_ref"]).resolve() == ink_path.resolve(), f"{path}.ink_ref does not match {ink_path}") + require((ROOT / data["source_fixture_ref"]).exists(), f"{path}.source_fixture_ref does not exist") + validate_text_blocks(data["local_awareness_summary"], f"{path}.local_awareness_summary") + + controls = data["projection_controls"] + require_keys( + controls, + ["frame_controls", "authority_boundaries", "object_custody", "required_semantics", "forbidden_resolutions"], + f"{path}.projection_controls", + ) + for key, items in controls.items(): + validate_text_blocks(items, f"{path}.projection_controls.{key}") + + ink_text = ink_path.read_text(encoding="utf-8") + branches = data["branches"] + require(isinstance(branches, list) and branches, f"{path}.branches must be non-empty") + saw_non_speech = False + for index, branch in enumerate(branches): + branch_path = f"{path}.branches[{index}]" + require_keys( + branch, + [ + "branch_id", + "ink_path", + "action_type", + "actor_intent", + "state_basis", + "reviewed_consequences", + "training_hooks", + ], + branch_path, + ) + require(branch["branch_id"] in ink_text, f"{branch_path}.branch_id is not tagged in Ink") + require(f"=== {branch['ink_path']} ===" in ink_text, f"{branch_path}.ink_path is not a knot in Ink") + require(branch["action_type"] in VALID_ACTION_TYPES, f"{branch_path}.action_type is invalid") + saw_non_speech = saw_non_speech or branch["action_type"] != "speak" + for list_key in ["state_basis", "reviewed_consequences", "training_hooks"]: + require(isinstance(branch[list_key], list) and branch[list_key], f"{branch_path}.{list_key} must be non-empty") + require(saw_non_speech, f"{path} must include at least one non-speech branch") + + mutation_policy = data["mutation_policy"] + require_keys(mutation_policy, ["automated", "manual_review_required"], f"{path}.mutation_policy") + require(mutation_policy["manual_review_required"], f"{path}.mutation_policy.manual_review_required must not be empty") + + audit = data["audit"] + require_keys(audit, ["reviewer", "review_status", "review_notes", "checks"], f"{path}.audit") + require(audit["review_status"] in {"accepted", "rejected", "needs_revision"}, f"{path}.audit.review_status is invalid") + require_keys( + audit["checks"], + [ + "uses_standard_branching_format", + "actor_local_context_only", + "includes_non_speech_actions", + "fuzzy_updates_marked_for_manual_review", + "aetheria_lore_content_readable", + ], + f"{path}.audit.checks", + ) + for key, value in audit["checks"].items(): + require(isinstance(value, bool), f"{path}.audit.checks.{key} must be boolean") + + +def validate_ink(path: Path) -> None: + compile_ink(path) + annotation_path = path.with_suffix(".training.json") + require(annotation_path.exists(), f"{path} is missing sidecar annotation {annotation_path.name}") + validate_annotation(annotation_path, path) + print(f"ok: {path}") + + +def main() -> int: + parser = argparse.ArgumentParser(description="Validate Ghostlight Ink examples.") + parser.add_argument("paths", nargs="*", type=Path, help="Ink files to validate.") + args = parser.parse_args() + + paths = args.paths or DEFAULT_INK_FILES + require(paths, "no Ink examples found") + for path in paths: + validate_ink(path) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main())