feat(#581): publish primitive P1 — version store + Docker runtime + origin-isolating gateway

[Weegy]

Summary

Phase P1 of issue #581 (publish primitive: agent-built internal web apps with immutable versions and rollback), per the phase-4c plan (docs/plans/phase4c-581-publish-prompt-2026-08-20.md). Builds on the #576 sandbox stack (@omadia/sandbox, merged to main).

This PR ships the library substrate only — version store, Docker runtime, origin-isolation gateway. No native tool, no route, no flag. That is P2 (stacked on this branch), wired through harness-orchestrator/src/plugin.ts's sandbox_execute_enabled-style seam per the plan.

What's in this PR

New package @omadia/publish (middleware/packages/harness-publish):

• publishStore.ts / postgresPublishStore.ts — PublishStore has no update/delete method by design: a republish can never mutate an existing version row, only create a new one. Postgres allocates version numbers via SELECT ... FOR UPDATE on a per-app counter row inside the same transaction as the version insert, so concurrent publishes to one app serialize rather than collide; the (app_id, version) primary key is the independent backstop.
• publish.ts — publish() orchestrates collect → hash → createVersion → deploy → setPointer. rollbackTo() calls only store.setPointer — its signature doesn't even accept a PublishRuntime, so it structurally cannot trigger a new build/deploy.
• treeCollector.ts — reads the published directory only through Sandbox.list()/read() (already traversal-clamped by @omadia/sandbox), recursing on paths list() itself returned. No raw filesystem path from agent input anywhere in this module.
• dockerPublishRuntime.ts — one immutable container per (appId, version) (deploy() is a no-op if that version's container already exists); one Docker volume per appId, mounted at $DATA_DIR in every version's container. That volume reuse is the entire $DATA_DIR durability mechanism: a file outside $DATA_DIR lives in the version's own container and is gone the moment a new version replaces it; a file inside $DATA_DIR is on the shared volume and survives every redeploy.
• publishGateway.ts — the origin boundary published apps run behind. Rejects any request whose Host does not end in a dedicated apps suffix (including an exact match on the admin host) before ever resolving an app backend; strips Cookie/Authorization before proxying; strips any Set-Cookie the app tries to scope with an explicit Domain=.

Migration 0045_publish_versions.sql: publish_versions (app_id, version) PK; publish_apps holds the next-version counter and current-version pointer with a composite FK back to publish_versions, so a pointer can only ever reference a version that genuinely exists.

Why the origin-isolation design

Cookies are scoped by the browser to a request's host, not its port (RFC 6265). Serving a published app on the admin/portal's own hostname — even on a different port — would let the app read the admin session cookie and set cookies the admin origin would honor. PublishGateway is a hard boundary: distinct host-suffix required, cookies stripped both directions.

Testing

• 32 tests in middleware/test/publish/ (stub tier, always on): store immutability incl. a concurrent-publish race test, tree collector, publish/rollbackTo orchestration (incl. a "rollback triggers no new deploy call" assertion), and the gateway origin-isolation suite (two plain http.Servers, no Docker/browser needed — proves a forwarded admin cookie never reaches the app backend and a domain-scoped Set-Cookie from the app never reaches the client).
• +10 more under SANDBOX_DOCKER_TEST=1 (opt-in, Durable per-scope sandbox with an execute tool #576's pattern): real container deploy + HTTP serve of a Node entrypoint, and an end-to-end $DATA_DIR round trip (file outside $DATA_DIR gone after redeploy; file inside survives). Ran locally against a real Docker daemon — all pass, containers/volumes cleaned up after.
• publishStore.pg.test.ts skips cleanly with no test Postgres configured (same convention as postgresSandboxRegistry.pg.test.ts).
• Combined test/publish/** + test/sandbox/**: 89/89 passing, exit 0.
• Mutation-checked (rebuilt dist/ between each probe and after restoring, since the orchestrator consumes @omadia/sandbox/@omadia/publish from dist/):
  • Reverted the gateway's Set-Cookie Domain= filter → the isolation suite failed exactly the "strips a Set-Cookie..." test (5 pass / 1 fail).
  • Reverted DockerPublishRuntime's containerExists no-op guard → the "no-op when already deployed" test failed (7 pass / 1 fail).
  • Reverted treeCollector's maxFiles cap → the "throws PublishTreeTooLargeError" test failed (5 pass / 1 fail).
  • All three restored; full suite re-verified 32/32 green after rebuild.
• node scripts/check-core-decoupling.mjs: held at 3296 (unchanged — no dev-runner-family literals touched, including in comments).
• npm run typecheck:test (test-typecheck ratchet): held at 406 known errors (unchanged) — the new @ts-expect-error compile-time proof in publishStore.test.ts (asserting PublishStore has no updateVersion/deleteVersion) type-checks clean.
• Full npm run build (root + all workspace packages incl. the new one) and npm run typecheck -w @omadia/publish: clean.
• npx eslint packages/harness-publish/src/: clean, no output.

Blast radius

• New package, new migration, no existing runtime code touched. middleware/package.json build/dev/typecheck/lint script chains got @omadia/publish added (mirroring every other workspace package's registration) — no other repo file changed.
• Migration 0045 is additive (CREATE TABLE IF NOT EXISTS), applied in filename order by the existing multi-orchestrator migrator — no other migration or registration list needed updating (confirmed against middleware/migrations/README.md).
• Nothing in src/index.ts, agentBuilder.ts, harness-orchestrator/src/plugin.ts, GrantStore, or any credential/skill/sandbox source was modified — this phase is purely additive library code, consumed nowhere yet.
• No native tool, no route, no operator flag — nothing changes for any existing deployment until P2 wires a tool behind a flag.

Migration number

0045 (middleware/migrations/0045_publish_versions.sql) — confirmed next-free after 0044 (sandbox_registry, #576 P3).

Open questions for Marcel

1. Runtime image: v1 supports only a Node entrypoint (node:20-alpine, PORT/DATA_DIR env convention). A "static site" publish is just a small Node script serving its own files — there's no separate static-file-serving code path. Good enough for v1, or worth a dedicated static mode before P2?
2. Stale version cleanup: every version keeps its own container running forever (immutable, but also never torn down). There's no reaper analog for publish versions in this PR — deliberately out of scope, but worth an issue before this sees real traffic.
3. Apps host suffix / reverse-proxy config: PublishGateway takes appsHostSuffix as a constructor option; actual DNS/reverse-proxy wiring for a real apps domain is an operator/deployment decision for P2 or later, not decided here.

Stack

Base: origin/main (post-#576 merge, includes the #576 P1–P3 sandbox stack). This is the first PR in the #581 stack — P2 (native tools behind a flag), P3 (GrantStore sharing), and optional P4 (admin version list) will stack on top per the phase-4c plan.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}