Orchestrata Ultimate › Plans › briefs › int-01-release-scaffold

INT-01 — SPEC-125 delta + release scaffold — brief for one qwen3-coder-next run

Source: plans/briefs/int-01-release-scaffold.md at 8a2cb42ad · last changed 2026-10-19 · first committed 2026-10-19 · 146 lines.

Prose pending.

Plan text

INT-01 — SPEC-125 delta + release scaffold — brief for one qwen3-coder-next run

DESIGN_WAIVER: none — the design exists and is ruled. Authority: ADR-0113 (integration L1 builds now), packages/integration/design/decisions.md D-I1 + D-I13, packages/integration/increments/README.md row INT-01, packages/integration/design/design.md (module rows + entry-point table). INT-01 ONLY — do NOT start INT-02..INT-25; do NOT lift any frozen module; this increment is design delta + scaffold.

Model-routing note (RUL-037): .py-fenced brief on qwen3-coder-next by Mohamed's explicit session instruction (stated override; M2 not landed). Coordinator verifies before commit. Workers do not commit.

Goal

packages/integration/ gains: (1) the PROPOSED SPEC-125 delta, (2) the orchestrata package inits, (3) the release pyproject.toml — every runtime component pinned by version, console scripts per D-I5, lock pins via the AD-41/SK-5 constraint mechanism, (4) env-profile assets recorded as integration-owned data. ~40 toml lines + inits + one delta document. No residue reopened in the eight landed packages.

Fence — create ONLY under packages/integration/

packages/integration/design/spec-125-delta.md
packages/integration/pyproject.toml
packages/integration/src/orchestrata/__init__.py
packages/integration/src/orchestrata/kernel/__init__.py
packages/integration/src/orchestrata/cli/__init__.py

Nothing outside the fence. No commit, no git add. No edits to the eight landed packages, no edits to increments/README.md (status flips are the coordinator's), no realize run, no REQ minting.

Read first (all small, all authoritative)

1. packages/integration/increments/README.md — the INT-01 row (the increment's exact scope) and the header's §7.8 brief-section list (your delta document mirrors the Requirements shape).
2. packages/integration/design/decisions.md — D-I1 (SPEC-125 free, ids PROPOSED not minted, "design-only, no realize run"), D-I13 (INT-01 first, integration last, the cut-over gate lives here), D-I5 (console scripts), D-I2 (landing names the delta pins).
3. packages/integration/design/design.md — the class diagram's 7 note for rows (REQ-125-001..007 proposed) and the module-rows table (REQ-125-901..915 proposed), the entry-point table, §Env-profile loading (the seams + the §5.6 "profiles are integration-owned DATA" line).
4. The landed pattern to COPY for the pyproject: packages/gateway/pyproject.toml (constraint-dependencies block, project metadata shape) and packages/governance/design/decisions.md D-G33 (AD-41/AD-44: pins read from the frozen uv.lock with tomllib, emitted as [tool.uv] constraint-dependencies).

Deliverables

1. design/spec-125-delta.md (PROPOSED)

• Header: SPEC-125 PROPOSED — integration (orchestrata, the composed release). Status: PROPOSED; realize mints REQ-125-* at intake; every id in this delta is a PROPOSAL (D-I1).
• The 22 proposed requirement rows transcribed EXACTLY from design.md: 7 class rows (REQ-125-001..007: the five _XComponent adapters + ServiceResult + InfraReport, each with its frozen origin) and 15 module rows (REQ-125-901..915: the module table's lands as + LOC + surface).
• The D-I2 landing-name table (including orchestrata.api for the frozen top-level cli, and the AD-40 (1) orchestrata.cli.session shim) — the delta PINS these names (the veto window closes at INT-01 intake).
• Env-profile assets recorded: env/{dev,test,prod}.env, env/ast-roots.env, env/toolchain.env are integration-owned DATA (census §5.6); promotion machinery is plugin's (promote_env.py imports only plugin modules — census §5.5). Recording = this section; do NOT copy env files.
• The ruling-gate ledger from increments/README.md (E-1 ×18 increments, N4 ×1, N-I1 ×1) with the orchestrata-mint-token console script marked N4-GATED (proposed, not active until N4 clears).

2. Release pyproject.toml

• Project name orchestrata, version 0.1.0, requires-python matching the landed packages (read gateway's).
• Dependencies: every runtime component pinned by version — MEASURE each landed package's actual version from its own pyproject (do not assume 0.1.0 for all eight: contracts, governance, knowledge_graph (import orchestrata_kg), kernel, session, volks, gateway, tools) and pin exactly (orchestrata-contracts==<measured> etc.). The packages are path-sourced in this repo: follow how the landed packages reference each other ([tool.uv.sources] path entries) — copy that shape from gateway's pyproject.
• Third-party runtime lines measured into the increments README/D-I13 (click, pyjwt, websockets, fastapi, uvicorn, pyyaml, anyio, neo4j, redis) resolved against the frozen lock via [tool.uv] constraint-dependencies — copy gateway's mechanism verbatim; pin versions from the repo-root frozen uv.lock (read the locked versions; do not invent).
• Console scripts (D-I5): orchestrata = "orchestrata.kernel.cli_main:main", session = "orchestrata.cli.session:main" — both point at modules that LAND IN LATER INCREMENTS (INT-05..09 / INT-25); that is the designed order, declare them now. orchestrata-mint-token is N4-gated: declare it in a comment with its intended target, NOT in the table.
• No build-system deviation: copy the landed packages' hatchling/setuptools choice exactly.

3. Package inits

src/orchestrata/__init__.py, src/orchestrata/kernel/__init__.py, src/orchestrata/cli/__init__.py: minimal — docstring naming the component (the composed release, SPEC-125 PROPOSED) and nothing else. No imports (every later increment's modules are function-scope-lazy by design, D-I3; an init that imports would break the assembly order). No __all__ (AD-24: zero frozen __all__ names in scope; the public surface is the console-script + module-entry table).

Traces

Deliberately UNTRACED (two-lane rule): SPEC-125 is PROPOSED, its REQ ids are not minted, so no id may be cited yet (RUL-013/trace-lint would flag them dangling). The delta document itself is the citation surface; stamping happens when realize mints at intake. Say so in the init docstrings' component line.

VERIFY (run exactly these from the repo root; report real outputs)

grep -c "==" packages/integration/pyproject.toml
grep -n "constraint-dependencies" packages/integration/pyproject.toml
grep -n "orchestrata.kernel.cli_main:main\|orchestrata.cli.session:main" packages/integration/pyproject.toml
grep -c "REQ-125-" packages/integration/design/spec-125-delta.md          # expect 22
grep -n "import " packages/integration/src/orchestrata/__init__.py packages/integration/src/orchestrata/kernel/__init__.py packages/integration/src/orchestrata/cli/__init__.py   # expect NOTHING
uv lock --project packages/integration --check 2>&1 | tail -3 || uv lock --project packages/integration 2>&1 | tail -5
.venv/bin/ruff check packages/integration/src 2>/dev/null || true

If uv lock cannot resolve offline, report the exact error — do NOT loosen pins to make it resolve; resolution failures against path sources are the coordinator's call.

Done

Reply with: the five created paths; the measured component versions table (package → version pinned); the frozen-lock third-party pin lines you copied; the uv lock result verbatim; the VERIFY outputs; and anything in the design you could not execute faithfully (named, not silently dropped).

REWORK — run 1 was REJECTED on these six measured failures (2026-10-20, coordinator verdict). Read before starting; repeating any one fails run 2.

1. FENCE: run 1 created env-integration/{dev,test,prod}.env AT THE REPO ROOT. The fence is packages/integration/ and the env-profile deliverable is a RECORDED SECTION in the delta document ("Recording = this section; do NOT copy env files"). Create no env files anywhere.
2. FABRICATED DATA: run 1's prod.env invented 10.53.3.11/10.53.3.10. There is no 10.53.3.x subnet: prod is 10.53.1.0/24 (env/prod.env: REDIS_HOST=10.53.1.10, KG_ROUTING_URI=neo4j://10.53.1.160:7691), test fleet is 10.53.2.x. NEVER write an IP that is not measured from env/*.env. (Moot if you obey #1.)
3. THE DELTA'S CORE IS THE 22 REQ ROWS: run 1's grep -c "REQ-125-" = 0. The file is packages/integration/design/spec-125-delta.md (exact name) and must transcribe ALL 22 proposed rows from design.md — 7 class rows (REQ-125-001..007 from the classDiagram note for lines) + 15 module rows (REQ-125-901..915 from the module-rows table, with lands as + LOC + surface). VERIFY greps for 22.
4. PINS: components pinned EXACTLY (orchestrata-contracts==<version measured from that package's own pyproject.toml>) in dependencies, WITH the path sources in [tool.uv.sources] (gateway's shape). Third-party: EXACTLY the nine D-I13 lines (click, pyjwt, websockets, fastapi, uvicorn, pyyaml, anyio, neo4j, redis) at the versions locked in the repo-root uv.lock — as [tool.uv] constraint-dependencies copied from gateway's block. NO other third-party deps: run 1 invented httpx/typer/psutil/tiktoken/ watchfiles/prometheus-client/jinja2/pydantic/cxpt/protobuf/msgpack/torch + a pytorch-cpu index and dropped pyjwt/anyio. The design's measured runtime lines are the only ones; anything you think is missing goes in your reply as a named observation, NOT into the file.
5. INITS: EXACTLY THREE — src/orchestrata/__init__.py, src/orchestrata/kernel/__init__.py, src/orchestrata/cli/__init__.py (the session console script needs orchestrata.cli to be a package; INT-25 lands orchestrata/cli/session.py there). Run 1 created 6 invented sub-namespaces (orchestrata/{contracts,governance,kg,session,volks,tools} — NONE exist in the D-I2 landing map) and OMITTED orchestrata/cli. Docstring-only, zero imports, no __all__.
6. HONESTY: run 1 claimed files were "already created in earlier work" — file timestamps proved it created them itself 40 minutes earlier, and the 2026-10-19 analysis had measured ZERO Python files in packages/integration. Report only what you did THIS run; the Done format's verbatim outputs are mandatory (component-versions table, uv lock result, every VERIFY line output).

Related

• Plans
• Orchestrata Ultimate — project index
• Workflow
• Tasks