ARN-66: port Foresight file-write prompt contracts

docs/proofs/2026-06-18-arn-66-foresight-port.md

@@ -0,0 +1,142 @@
+# ARN-66 Foresight Port And Topology Proof
+
+Date: 2026-06-18
+
+## Scope
+
+TemperPaw worktree: `/Users/seshendranalla/.codex/worktrees/0be7/temperpaw`
+Branch: `codex/arn-66-foresight-port`
+Remote: `origin=https://github.com/nerdsane/temperpaw.git`
+
+This proof covers the ARN-66 port/readiness lane for the Deep Sci-Fi/Foresight engine:
+
+- confirm canonical deployment topology;
+- check whether searched-corridor fixes landed only in openpaw or also in canonical Foresight;
+- port the prompt/file-write recipe delta to GitHub main;
+- avoid duplicating ARN-65's broader self-heal lane.
+
+This is not a fresh productive end-to-end run proof. It prepares the path for one.
+
+## Deployment Topology Evidence
+
+Railway project `openpaw-seshendranalla` contains both services:
+
+- `openpaw` service id `4a8dedaa-8a2e-4cdd-945b-e06c781bb3f0`
+- `foresight` service id `ed6c91b5-d235-4286-964a-41acdab47c49`
+
+Canonical Foresight evidence:
+
+- Railway service config source image: `ghcr.io/nerdsane/temperpaw:sha-e1c3968`
+- latest deployment: `5110497a-...`, SUCCESS at `2026-06-18 13:21:41 UTC`
+- database host: `aws-1-us-west-1.pooler.supabase.com`
+- `TEMPER_POSTGRES_MAX_CONNECTIONS=40`
+- `DD_SERVICE=foresight`
+- `DD_DBM_DATABASE_SERVICE=foresight-supabase`
+- `LLM_PROVIDER=openai_codex`
+- `LLM_MODEL=gpt-5.5`
+- public readiness: `https://foresight-production-72d1.up.railway.app/readyz` returned ready
+- Genesis bootstrap ref includes `temperpaw/paw-foresight@659e40c663024af1acf1ed6d2a39d872d3dbdf14`
+
+Openpaw comparison evidence:
+
+- Railway service config source image: `ghcr.io/nerdsane/temperpaw:sha-5c3c05f`
+- latest deployment: `b1b96383-...`, SUCCESS at `2026-06-18 15:23:06 UTC`
+- database host: `postgres.railway.internal`
+- `DD_SERVICE=temperpaw`
+- `DD_DBM_DATABASE_SERVICE=temperpaw-postgres`
+- `LLM_PROVIDER=openai_codex`
+- `LLM_MODEL=gpt-5.5`
+- Genesis bootstrap ref includes `temperpaw/paw-foresight@01ac826b9604ef1828eee146724a44953375ebfb`
+
+Conclusion: canonical deployment for this run track is `foresight` on Supabase, not `openpaw` on Railway Postgres. Both checked deployments are still configured for Codex/OpenAI provider `openai_codex` with model `gpt-5.5`; no provider switch is part of this work.
+
+## Commit And Genesis Evidence
+
+Local Git evidence:
+
+- `e3f2fbaf fix(foresight): give session agents an explicit file-write recipe (no API-guessing)` is not an ancestor of `origin/main`.
+- `22795542 fix(foresight): self-heal the endpoint writer phase (Endpoint.Sampled)` is not an ancestor of `origin/main`.
+- both are present on the searched-corridor branch, not GitHub main.
+
+Genesis evidence:
+
+- canonical `paw-foresight@659e40c663024af1acf1ed6d2a39d872d3dbdf14` has 90 files and includes `wasm/sample_endpoints/src/lib.rs`, `specs/endpoint.ioa.toml`, and the other corridor WASM modules.
+- canonical `paw-foresight@659e40...` contains Endpoint self-heal markers in `specs/endpoint.ioa.toml`, including `Sampled`, `ResumeWriter`, `state_timeout`, `allow_indefinite_states`, and `UnderRepair`.
+- canonical `paw-foresight@659e40...` also contains earlier file-write guidance in WASM prompt source, but still contains the bare `<file-id-from-temper.write>` placeholder in all six checked WASM prompt modules.
+- openpaw `paw-foresight@01ac826b9604ef1828eee146724a44953375ebfb` has 29 files and does not include the checked `paw-foresight` WASM/spec paths, so it is not the canonical app bundle for this lane.
+
+Conclusion: the self-heal class from `22795542` is already visible in the canonical deployed Genesis ref, while GitHub main is missing it. ARN-65 is actively owning the broader self-heal source convergence. This ARN-66 branch therefore ports only the prompt/file-write delta, with a tighter tested recipe than the deployed `659e40...` bundle currently exposes.
+
+## Red Test
+
+Added failing contract tests first in these modules:
+
+- `sample_endpoints`: `writer_prompt_gives_explicit_file_write_recipe`
+- `seed_world`: `surveyor_prompt_gives_explicit_file_write_recipe`
+- `spawn_adversaries`: `adversary_prompt_gives_explicit_file_write_recipe`
+- `spawn_repairers`: `repairer_prompt_gives_explicit_file_write_recipe`
+- `render_artifacts`: `author_prompt_gives_explicit_file_write_recipe`
+- `animate_dwellers`: `dweller_prompt_gives_explicit_file_write_recipe`
+
+Initial targeted runs failed because GitHub main did not show literal `temper.write("/...md", ...)` calls in the executable prompts and left the ambiguous file-id placeholder.
+
+## Green Change
+
+Executable prompts now tell agents:
+
+- the workspace already exists;
+- `temper.write` is the only file creation path;
+- not to create Files, Directories, or Workspaces manually;
+- the exact write path to call for each phase;
+- that `temper.write` returns `file_id`, `path`, and `workspace_id`;
+- to pass `result["file_id"]` into the relevant completion action.
+
+Updated agent manuals for surveyor, endpoint writer, adversary, repairer, and dweller to match. The endpoint-writer manual was also aligned from stale `SubmitForRepair` language to the current `BundleWritten` diversity-gate contract.
+
+## Automated Verification
+
+Commands completed successfully after implementation:
+
+```sh
+cargo test --manifest-path os-apps/paw-foresight/wasm/sample_endpoints/Cargo.toml
+cargo test --manifest-path os-apps/paw-foresight/wasm/seed_world/Cargo.toml
+cargo test --manifest-path os-apps/paw-foresight/wasm/spawn_adversaries/Cargo.toml
+cargo test --manifest-path os-apps/paw-foresight/wasm/spawn_repairers/Cargo.toml
+cargo test --manifest-path os-apps/paw-foresight/wasm/render_artifacts/Cargo.toml
+cargo test --manifest-path os-apps/paw-foresight/wasm/animate_dwellers/Cargo.toml
+git diff --check
+```
+
+Results:
+
+- `sample_endpoints`: 11 passed
+- `seed_world`: 7 passed
+- `spawn_adversaries`: 8 passed
+- `spawn_repairers`: 13 passed
+- `render_artifacts`: 7 passed
+- `animate_dwellers`: 7 passed
+- whitespace check passed
+
+## Deep Sci-Fi UI Status
+
+Read-only inspection found the run-progress UI on local Deep Sci-Fi branch `codex/dsf-2`, not on the deployed Railway service:
+
+- repo: `/Users/seshendranalla/Development/deep-sci-fi-worktrees/dsf-2`
+- branch: `codex/dsf-2`, ahead of `origin/codex/dsf-2` by 2 commits
+- commits: `dfe5a904 Add live run progress UI with stall detection`, `efcc166f Add e2e coverage for live run progress panel`
+- changed files include `platform/components/world/RunProgressLive.tsx`, `platform/app/api/world/[id]/run-status/route.ts`, `platform/lib/run-status.ts`, `platform/lib/temper-server.ts`, and e2e/unit coverage.
+
+The UI path uses `TEMPER_API_URL`, `TEMPER_API_KEY`, and `TEMPER_TENANT` through the server-side helper; no openpaw URL hardcode was found in the run-progress path. The deployed DSF Railway backend is sourced from `arni-labs/deep-sci-fi`, root `platform/backend`, with latest successful deploy `2026-04-04 12:57:10 UTC` at commit `deacc27a...`; its variables do not include the Temper proxy variables needed by the run-progress API. A second DSF repo PR/deploy is required before the run-progress UI can serve as canonical Foresight run proof.
+
+## ADR Judgment
+
+No new ADR was added. This change does not alter entity specs, policies, storage, triggers, deployment behavior, or orchestration architecture; it ports and tests prompt/operator guidance for existing actions and tools.
+
+## Fresh Run Readiness Checklist
+
+- Merge/publish this prompt-file-write port into the canonical `paw-foresight` Genesis app.
+- Let ARN-65 finish and publish the broader source convergence for Endpoint.Sampled, UnderRepair, World.Active, and Seeding self-heal, or explicitly pin to the already deployed canonical `659e40...` behavior if that remains the accepted production baseline.
+- Configure and deploy the DSF run-progress UI against canonical Foresight with `TEMPER_API_URL=https://foresight-production-72d1.up.railway.app`, the correct tenant, and a server-side API key.
+- Start one fresh productive run against `foresight`/Supabase.
+- Capture OData proof for the new world: World state, Endpoint state progression, Sessions activity, file ids written by `temper.write`, and final artifacts/stories.
+- Confirm in Datadog under `DD_SERVICE=foresight` and `DD_DBM_DATABASE_SERVICE=foresight-supabase` that the run uses Supabase and does not fall back to openpaw Railway Postgres.

os-apps/paw-foresight/agents/adversary/AGENT.md

@@ -33,13 +33,21 @@ In hindcast worlds you have NO web access; attack from the corpus, the skeleton,
 
 The API silently drops unknown fields. Use these exact names.
 
-## Self-Reporting Completion
+## Writing Your Challenge Log
+
+`temper.write` is the ONLY way to create a file, and your workspace already exists. Never create Files, Directories, or Workspaces yourself, and never invent a file-creation API through `temper.action` — `temper.write` does the whole job. Call it exactly like this:
+
+```python
+result = temper.write("/challenge-log.md", "...markdown: each attack with its reasoning...")
+# result == {"file_id": "...", "path": "...", "workspace_id": "..."}
+challenge_log_file_id = result["file_id"]
+```
 
-Write a challenge log with `temper.write` (markdown: each attack with its reasoning), then:
+## Self-Reporting Completion
 
 ```python
 temper.action("Paths", "<path_id>", "ChallengeComplete", {
-    "challenge_log_file_id": "<file-id-from-temper.write>",
+    "challenge_log_file_id": challenge_log_file_id,
     "challenge_flags": '[{"kind": "...", "severity": "...", "note": "..."}]'
 })
 temper.done("complete")

os-apps/paw-foresight/agents/dweller/AGENT.md

@@ -36,12 +36,16 @@ Your within-frontier calls are graded by the system like everything else in this
 
 The API silently drops unknown fields. Use these exact names.
 
+### Writing files
+
+`temper.write` is the ONLY way to create a FILE, and your workspace already exists. Never create Files, Directories, or Workspaces yourself, and never invent a file-creation API — `temper.create` is for Artifacts only, never for files. Every call returns `{"file_id": "...", "path": "...", "workspace_id": "..."}`; use `result["file_id"]` for the file ids below.
+
 ### Filing a traversal
 ```python
-# After writing your traversal notes with temper.write:
+result = temper.write("/traversal-notes.md", "...your lived timeline notes...")
 temper.action("Dwellers", "<your_dweller_id>", "RecordTraversal", {
     "path_id": "<path_id>",
-    "traversal_note_file_id": "<file-id-from-temper.write>"
+    "traversal_note_file_id": result["file_id"]
 })
 ```
 
@@ -62,9 +66,9 @@ artifact = temper.create("Artifacts", {
     "title": "Short, in-world title",
     "author_dweller_id": "<your_dweller_id>"
 })
-# temper.write the full story (markdown), capture the file id, then:
+result = temper.write("/story.md", "...the full story, markdown...")
 temper.action("Artifacts", "<artifact_id>", "SubmitForCheck", {
-    "content_file_id": "<file-id>",
+    "content_file_id": result["file_id"],
     "cited_node_ids": '["<node-id>", "<node-id>"]'
 })
 ```

os-apps/paw-foresight/agents/endpoint-writer/AGENT.md

@@ -11,7 +11,7 @@ World.SampleEndpoints created your Endpoint entity, assigned its driver stance (
 - Optionally a corpus file and a driver basis file
 - Web tools, unless this is a hindcast world
 
-You write one document bundle, submit it for repair, and finish. Repairers will work backward from your documents; their repair costs decide your endpoint's weight — it is earned, not asserted.
+You write one document bundle, report it with `BundleWritten`, and finish. The diversity gate decides which bundles move into repair. Repairers will work backward from your documents; their repair costs decide your endpoint's weight — it is earned, not asserted.
 
 ## Your Job
 
@@ -22,32 +22,42 @@ Then write a document bundle: 2-4 documents, every one dated AT the target date
 - a news item,
 - at least one in-world primary document (a filing, a review, a changelog).
 
-Documents must contain specific dates, named actors, and numbers. Vague futures cannot be repaired. Save the whole bundle as ONE markdown file with `temper.write`.
+Documents must contain specific dates, named actors, and numbers. Vague futures cannot be repaired. Save the whole bundle as ONE markdown file with `temper.write` (see below) — your workspace already exists; never create Files, Directories, or Workspaces yourself.
 
 In hindcast worlds you have NO web access by design, and you never reference anything dated after the world's vantage.
 
 ## Field Names (CRITICAL)
 
 The API silently drops unknown fields. Use these exact names.
 
+## Writing Your Bundle
+
+`temper.write` is the ONLY way to create a FILE, and your workspace already exists. Never create Files, Directories, or Workspaces yourself, and never invent a file-creation API through `temper.action`. Call it exactly like this:
+
+```python
+result = temper.write("/bundle.md", "...the full markdown bundle...")
+# result == {"file_id": "...", "path": "...", "workspace_id": "..."}
+bundle_file_id = result["file_id"]
+```
+
 ## Self-Reporting Completion
 
 ```python
-temper.action("Endpoints", "<endpoint_id>", "SubmitForRepair", {
-    "bundle_file_id": "<file-id-from-temper.write>",
+temper.action("Endpoints", "<endpoint_id>", "BundleWritten", {
+    "bundle_file_id": bundle_file_id,
     "summary": "<one line>",
     "author_agent_id": "<your_agent_id>"
 })
 temper.done("complete")
 ```
 
-This is critical — SubmitForRepair is what spawns the repairer. An unwritten or unreported bundle is a dead endpoint.
+This is critical — `BundleWritten` parks the endpoint for the diversity gate. An unwritten or unreported bundle is a dead endpoint.
 
 ## Principles
 
 - Native to the target date: in-world artifacts, not forecasts.
 - Hold your assigned stance — the spread is the point; don't drift back to consensus.
 - Never contradict a determined node.
 - Specifics or nothing: dates, named actors, numbers.
-- One markdown file, one SubmitForRepair, then temper.done.
+- One markdown file, one BundleWritten, then temper.done.
 - You will not repair your own endpoint — repairers are always distinct agents (Cedar enforces it).

os-apps/paw-foresight/agents/repairer/AGENT.md

@@ -44,13 +44,21 @@ temper.create("EventNodes", {
 })
 ```
 
-## Self-Reporting Completion
+## Writing Your Repair Log
+
+`temper.write` is the ONLY way to create a FILE, and your workspace already exists. Never create Files, Directories, or Workspaces yourself, and never invent a file-creation API — `temper.create` is for EventNodes only, never for files. Call `temper.write` exactly like this:
+
+```python
+result = temper.write("/repair-log.md", "...markdown: the backward chain with your reasoning...")
+# result == {"file_id": "...", "path": "...", "workspace_id": "..."}
+repair_log_file_id = result["file_id"]
+```
 
-Write a repair log with `temper.write` (markdown: the backward chain with your reasoning), then:
+## Self-Reporting Completion
 
 ```python
 temper.action("Paths", "<path_id>", "RepairComplete", {
-    "repair_log_file_id": "<file-id-from-temper.write>",
+    "repair_log_file_id": repair_log_file_id,
     "required_node_ids": '["<event-node-id>", ...]',
     "cost_flags": '[{"kind": "...", "severity": "...", "note": "..."}]'
 })

os-apps/paw-foresight/agents/surveyor/AGENT.md

@@ -36,14 +36,24 @@ temper.create("EventNodes", {
 })
 ```
 
+## Writing Your Skeleton Summary
+
+`temper.write` is the ONLY way to create a FILE, and your workspace already exists. Never create Files, Directories, or Workspaces yourself, and never invent a file-creation API — `temper.create` is for EventNodes only, never for files. Call it exactly like this:
+
+```python
+result = temper.write("/skeleton.md", "...one-page skeleton summary, markdown...")
+# result == {"file_id": "...", "path": "...", "workspace_id": "..."}
+graph_snapshot_file_id = result["file_id"]
+```
+
 ## Self-Reporting Completion
 
-Write a one-page skeleton summary with `temper.write` (markdown), then report to the World before finishing:
+Report to the World before finishing:
 
 ```python
 temper.action("Worlds", "<world_id>", "SeedComplete", {
     "skeleton_node_count": "<n>",
-    "graph_snapshot_file_id": "<file-id-from-temper.write>"
+    "graph_snapshot_file_id": graph_snapshot_file_id
 })
 temper.done("complete")
 ```