monoid-agent-kernel 0.19.1__tar.gz → 0.19.2__tar.gz

{monoid_agent_kernel-0.19.1 → monoid_agent_kernel-0.19.2}/.github/workflows/ci.yml

@@ -146,6 +146,10 @@ jobs:
           tests/test_backend_dbos_run.py
           tests/test_backend_dbos_control.py
           tests/test_dbos_control_models.py
+          tests/test_dbos_hosted_control.py
+          tests/test_dbos_hosted_run.py
+          tests/test_dbos_owned_runtime.py
+          tests/test_dbos_runtime_host.py
           tests/test_dbos_run_driver.py
           tests/test_dbos_run_models.py
           --durations=10
@@ -179,6 +183,16 @@ jobs:
       - name: Verify optional dependencies
         if: matrix.install == 'all-extras'
         run: python -c "import dbos, openai, httpx, opentelemetry.sdk"
+      - name: Run installed conformance evidence smoke
+        if: matrix.install == 'minimal'
+        working-directory: ${{ runner.temp }}
+        run: |
+          python -m monoid_agent_kernel.conformance.runner \
+            --harness monoid_agent_kernel.reference.conformance:create_minimal_harness \
+            --json-out conformance.json \
+            --junit-out conformance.xml \
+            --evidence-dir conformance-evidence
+          python -c "from pathlib import Path; from monoid_agent_kernel.conformance import read_conformance_report, verify_conformance_report; loaded = read_conformance_report(Path('conformance.json')); assert loaded.status == 'loaded' and loaded.value is not None; report = loaded.value; reference = report.evidence[0]; result = verify_conformance_report(report, {reference.evidence_id: (Path('conformance-evidence') / reference.resource.name).read_bytes()}); assert result.verified and result.report_passed"
       - name: Run minimal Studio acceptance from installed package
         if: matrix.install == 'minimal'
         working-directory: ${{ runner.temp }}

{monoid_agent_kernel-0.19.1 → monoid_agent_kernel-0.19.2}/CHANGELOG.md

@@ -7,6 +7,53 @@ out in commit messages and here.
 
 ## [Unreleased]
 
+## [0.19.2] - 2026-07-19
+
+### Added
+
+- Added a Reference-private single-handle, snapshot-bounded event page reader with
+  monotonic-prefix and content-verified byte-offset anchors plus raw-read source-work metrics,
+  supplying the sparse index's verified scan primitive while preserving Core cursor semantics
+  inside the protected append-only run-directory boundary.
+- Added a Reference-private process-local sparse offset index that retains verified anchors,
+  stages bounded candidates during successful page scans, performs logarithmic warm lookup, and
+  rebuilds safely after detected source invalidation or process restart.
+- Bounded the sparse index's retained source slots with a pinned least-recently-used policy and
+  an authoritative uncached fallback for saturated admission, plus cache-capacity metrics.
+- Wired one backend-owned sparse event index into root, descendant, and diagnostics projections,
+  with configurable retained-source capacity and unchanged Core subscription semantics.
+- Added exact-byte conformance evidence descriptors plus a checked reader that reads retained v1
+  reports into the current typed provenance model with provenance explicitly unavailable.
+- Added offline minimal-agent report verification of exact-byte digest integrity, sanitized
+  self-asserted target metadata, profile binding, lifecycle completeness, rule-reference coverage,
+  and internal report/evidence semantic consistency.
+- Added opt-in v2 external reports. When `--evidence-dir` is supplied with an evidence-capable
+  adapter, the runner retains content-addressed normalized evidence, binds all four rules to its
+  content-addressed evidence reference, self-verifies, then publishes retained evidence and
+  configured JUnit/JSON outputs before stdout. Default report-only and legacy adapter runs preserve
+  the v1 output contract.
+- Added a Reference-private DBOS 2.26 owned-runtime adapter that binds workflow registration,
+  identity-scoped enqueue and retrieval, queue, launch, and shutdown operations to one captured
+  singleton and registry, rejects Cloud/Conductor mode, and verifies global identity plus
+  DBOS-owned thread cleanup before ownership release.
+- Added a single-owner Reference-private DBOS runtime host that composes hosted control and run
+  participants under one captured runtime, with deterministic workflow identity, an explicit
+  shared surface-configuration contract, pre-launch workflow/listener aggregation, one
+  launch/shutdown lifecycle, pre-destroy admission drain, deadline-bounded close, and process
+  fencing when participant drain or ownership verification is uncertain.
+- Added a Reference-private hosted control participant that defers workflow, queue, admission,
+  and shutdown ownership to the single DBOS runtime host while preserving standalone behavior.
+- Added a Reference-private hosted run participant with host-owned workflow, queue, admission,
+  active-drive, and shutdown lifecycle while keeping checkpoint semantics portable.
+
+### Fixed
+
+- Projected MIN-03 result identity and completion checks as booleans so raw run identifiers and
+  result status strings do not enter conformance report projections.
+- Treated newline-terminated event-log records as committed and repaired uncommitted crash
+  fragments before recorder or direct append, preventing malformed concatenation and sequence
+  reuse during restart. Committed records with invalid sequence fields now fail closed.
+
 ## [0.19.1] - 2026-07-16
 
 ### Changed

{monoid_agent_kernel-0.19.1 → monoid_agent_kernel-0.19.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: monoid-agent-kernel
-Version: 0.19.1
+Version: 0.19.2
 Summary: Lightweight durable agent kernel for product integrations
 Project-URL: Homepage, https://github.com/hoonseokyoon/monoid-agent-kernel
 Project-URL: Repository, https://github.com/hoonseokyoon/monoid-agent-kernel

{monoid_agent_kernel-0.19.1 → monoid_agent_kernel-0.19.2}/docs/COMPATIBILITY.md

@@ -5,12 +5,15 @@ namespace aliases, and source aliases. The machine-readable source is
 `monoid_agent_kernel.core.compatibility.PUBLIC_ARTIFACT_COMPATIBILITY`; the table below is
 checked against it in CI.
 
-Experimental optional Reference profiles are outside this stable inventory. In v0.18,
-`DbosResumeCommand` and `DbosRunReceipt` are experimental Reference operational records for the
-finite-activation proof. Core compatibility excludes them. Keep the DBOS `application_version`
-stable while pending work must recover, drain that work before an incompatible workflow change,
-and treat their exported version constants as local profile identifiers without a rolling-reader
-guarantee. DBOS types and upgrade policy stay inside the optional Reference profile.
+Experimental optional Reference profiles sit outside this stable inventory. v0.19.2 treats
+`DbosResumeCommand`, `DbosRunReceipt`, and the DBOS-specific control envelope as experimental
+Reference operational records for the finite-activation profile. Their compatibility belongs to
+the DBOS profile rather than Core. Control workflow output uses the stable writer-only
+`CommandReceipt` listed below. Keep the DBOS `application_version` stable while pending work must
+recover, drain that work before an incompatible workflow change, and treat exported DBOS version
+constants and the internal control-envelope version as local profile identifiers without a
+rolling-reader guarantee. DBOS types and upgrade policy stay inside the optional Reference
+profile.
 
 ## Reader policy
 
@@ -23,8 +26,10 @@ guarantee. DBOS types and upgrade policy stay inside the optional Reference prof
   accept unknown identifiers.
 - `writer-only` formats have a public producer and no public serialized reader contract.
 
-`Missing id accepted` records an existing compatibility behavior. New producers must always
-write the current identifier.
+`current_writer` is the default producer identifier. The machine-readable `active_writers` tuple
+lists every identifier this release can emit; most artifacts contain only `current_writer`.
+`Missing id accepted` records an existing compatibility behavior. New producers write
+`current_writer` unless a documented variant selects another active writer.
 
 ## Versioned artifact inventory
 
@@ -60,12 +65,18 @@ write the current identifier.
 | `failure` | durable | `monoid.failure.v1` | permissive; missing id accepted | `monoid.failure.v1`<br>`native-agent-runner.failure.v1` |
 | `command-inbox` | durable | `monoid.command-inbox.v1` | strict | `monoid.command-inbox.v1` |
 | `command-receipt` | wire | `monoid.command-receipt.v1` | writer-only | None (writer-only) |
-| `conformance-report` | reference | `monoid.conformance-report.v1` | writer-only | None (writer-only) |
+| `conformance-report` | reference | `monoid.conformance-report.v1` | checked | `monoid.conformance-report.v1`<br>`monoid.conformance-report.v2` |
+| `conformance-evidence` | reference | `monoid.conformance-evidence.v1` | strict | `monoid.conformance-evidence.v1` |
 | `conformance-fixtures` | reference | `monoid.conformance-fixtures.v1` | strict | `monoid.conformance-fixtures.v1` |
 | `studio-chat` | reference | `studio.chat.v1` | strict | `studio.chat.v1` |
 | `studio-chat-message` | reference | `studio.chat.message.v1` | permissive; missing id accepted | `studio.chat.message.v1` |
 <!-- compatibility-registry:end -->
 
+The v0.19.2 conformance rollout keeps the default external report writer on v1 and adds an opt-in
+v2 evidence path after deploying its checked reader. Retained v1 reports migrate into the v2 typed
+model with provenance explicitly marked unavailable. `--evidence-dir` emits v2 when an enhanced
+adapter supplies retained evidence; consumers of that output need a v2 reader.
+
 Source locations and format-specific notes are available through
 `compatibility_registry()`. Integrators can serialize that result directly as JSON.
 
@@ -131,7 +142,8 @@ a web call, control delivery, and checkpoint resume before advancing the rollout
 4. Deploy readers first: gateways and backend recovery workers before clients and run workers.
 5. Resume a non-terminal checkpoint canary and verify its run metadata, event sequence, queued
    messages, hosted tasks, and blob references.
-6. Enable new writers. Confirm they emit the registry's `current_writer` identifiers.
+6. Enable new writers. Confirm each emitted identifier appears in the registry's `active_writers`;
+   use `current_writer` for the default producer path.
 7. Retain the pre-upgrade snapshot until recovery, Studio projection, proposal verification,
    and gateway smoke checks pass.
 

{monoid_agent_kernel-0.19.1 → monoid_agent_kernel-0.19.2}/docs/CONFORMANCE.md

@@ -50,6 +50,8 @@ optional external-agent envelope profile for runtimes that exchange messages wit
 The conformance package defines profile-specific Protocol families:
 
 - `MinimalAgentHarness`: reports one submission-to-result lifecycle and its event sequence.
+- `MinimalAgentEvidenceHarness`: optionally returns the same case with a closed, secret-minimized
+  evidence bundle from one invocation.
 - `ToolAgentHarness`: runs tool surface admission and generic approval behavior cases.
 - `ControlPlaneHarness`: runs decision and control audit sequencing behavior cases.
 - `DurableRunnerHarness`: runs event sequence, recovery metadata, and subagent diagnostics cases.
@@ -78,7 +80,8 @@ python -m monoid_agent_kernel.conformance.runner \
   --harness your_package.conformance:create_harness \
   --profile minimal-agent \
   --json-out build/conformance.json \
-  --junit-out build/conformance.xml
+  --junit-out build/conformance.xml \
+  --evidence-dir build/conformance-evidence
 ```
 
 Exit code `0` means every rule passed, `1` means at least one rule failed, and `2` means the runner
@@ -87,12 +90,78 @@ observations. `load_compatibility_fixtures()` supplies packaged historical wire
 payloads for downstream reader tests. JSON, JUnit, and console diagnostics retain a safe exception
 category and redact the exception body; keep raw stack traces in protected implementation logs.
 
-The v0.18 command-line runner executes the `minimal-agent` profile. Other profile harnesses remain
+The command-line runner executes the `minimal-agent` profile. Other profile harnesses remain
 Python test integrations. Store and broker implementers call
 `run_checkpoint_store_contract(factory, root)` and `run_capability_broker_contract(factory)`
 directly from their own pytest suites or CI tools. These functions return the same typed rule
 outcomes and carry no pytest dependency.
 
+## Provenance and retained evidence
+
+An evidence-retaining v2 report marks provenance `available` only while the caller owns the exact
+evidence bytes. The command-line runner emits that report when `--evidence-dir` is present and the
+adapter implements `MinimalAgentEvidenceHarness`. A report-only call or a legacy adapter preserves
+the v1 output contract. Programmatic callers use
+`monoid_agent_kernel.conformance.runner.execute_conformance(..., retain_evidence=True)` to receive
+the report and exact evidence artifacts from the same invocation.
+
+One normalized lifecycle bundle supports all four `MIN-*` outcomes. Every outcome references the
+stable evidence id `minimal-agent.lifecycle`. The runner stores the bytes under a content-addressed
+name such as:
+
+```text
+minimal-agent.lifecycle.sha256-<64 lowercase hexadecimal digits>.json
+```
+
+Resolve an artifact as `evidence_dir / report.evidence[0].resource.name`. The runner verifies the
+assembled report and bytes before publication, reuses an identical content-addressed artifact,
+and rejects conflicting content without overwriting it. Evidence publication requires atomic
+no-replace support; the runner fails before publishing the report when that primitive is
+unavailable. Publication writes evidence first,
+JUnit second, JSON last, and stdout after file outputs succeed. JSON plus retained evidence is the
+authoritative verification set. JUnit remains a secondary xUnit2-compatible CI projection with
+suite-level target, evidence, and per-rule reference descriptors; it never embeds the raw evidence
+bundle. Give each concurrent runner its own mutable JSON and JUnit destinations; content-addressed
+evidence directories may be shared.
+
+Offline verification does not invoke the original harness:
+
+```python
+from pathlib import Path
+
+from monoid_agent_kernel.conformance import (
+    read_conformance_report,
+    verify_conformance_report,
+)
+
+report_path = Path("build/conformance.json")
+evidence_dir = Path("build/conformance-evidence")
+loaded = read_conformance_report(report_path)
+assert loaded.status == "loaded" and loaded.value is not None
+report = loaded.value
+assert report.provenance_status == "available"
+reference = report.evidence[0]
+result = verify_conformance_report(
+    report,
+    {reference.evidence_id: (evidence_dir / reference.resource.name).read_bytes()},
+)
+assert result.verified
+```
+
+The closed evidence schema retains sanitized target identity, a domain-separated case fingerprint,
+lifecycle scalars, and event sequence/type pairs. It excludes raw run ids, provider errors, event
+payloads, model text, tool arguments, tokens, timestamps, filesystem paths, and environment data.
+`harness_id` is public adapter metadata; adapters must keep credentials, paths, and user data out of
+that field. The JUnit projection renders XML-forbidden code points as visible `#xHEX` tokens so
+public metadata cannot produce malformed XML.
+
+The harness adapter is the trusted translator and asserts that the normalized bundle reflects the
+tested runtime. Offline report verification first checks exact-byte digest integrity, then checks
+target/profile binding, lifecycle completeness, rule-reference coverage, and internal
+report/evidence semantic consistency. Target metadata remains a sanitized self-assertion. Producer
+authenticity, freshness, and adapter honesty require a trusted distribution channel, signature, or
+external attestation.
+
 ## Reference Full
 
 The `reference-full` profile runs the bundled Reference implementation through the concrete current

{monoid_agent_kernel-0.19.1 → monoid_agent_kernel-0.19.2}/docs/CONTRACTS.md

@@ -626,7 +626,89 @@ redrive.
 `from_seq` remains inclusive for backward compatibility. When `limit` is present, callers resume
 with `from_seq=next_seq` to avoid duplicates; omitting `limit` preserves the historical "return all
 events from N" behavior. `RunnerBackend.descendant_events(...)` uses the same pagination contract
-for subagent event streams authorized through an ancestor run token.
+for subagent event streams authorized through an ancestor run token. Stored event sequences are
+positive integers; `from_seq=0` remains the valid cursor for reading from before the first event.
+
+The physical JSONL commit marker is the terminating newline. Readers withhold any trailing bytes
+after the last newline, including an otherwise valid JSON object. Before a recorder or guarded
+direct append reopens the log, it removes that uncommitted suffix only when the status watermark
+does not advertise a later event. A later watermark or a malformed newline-terminated tail fails
+closed without changing the file. Logical `seq` values remain the public cursor; binary offsets
+are private storage details. Tail preparation runs only after the existing queued, live, or
+terminal sequence-owner decision; it validates storage and does not elect another writer. Status
+acts only as a contradiction guard. Writer restart continues to validate all committed sequences
+and fails on duplicate or decreasing physical values; the derived read index never seeds writers.
+
+The Reference package also provides an internal snapshot-bounded page-scan primitive that can
+begin at a content-verified `(seq, byte offset, next byte offset, record digest)` anchor. Tail
+capture, bounded scan, and tail-witness verification share one open file description, so pathname
+replacement cannot mix records from different files in one page. A concurrent append stays outside
+the captured committed prefix. The result reports decoded records, logical scan span, and raw bytes
+fetched by the Reference reader, including fixed-size buffer read-ahead, for deterministic scale
+tests.
+
+The run directory is a protected append-only trust boundary. Deployments reserve run-artifact write
+access for runtime event and metadata owners. Committed event records are immutable, and tool
+workspaces and untrusted processes have no write access to run artifacts. Persistent anchors derive
+transitively from a contiguous prefix originally verified from byte zero. Each warm seek rechecks
+the source identity and nonshrinking committed extent, then verifies the anchored record at its byte
+offset. The current snapshot's committed tail witness is verified before new anchors are minted.
+The in-memory primitive accepts only anchors minted while scanning a strictly increasing prefix.
+Within this boundary, every skipped prefix sequence remains below the anchor sequence, preserving
+Core page results.
+Each proof is process-local and bound to the normalized source path, open-file identity, and captured
+source metadata; copied or field-tampered anchors, cross-log anchors, truncated sources, and
+same-size sources with a changed modification timestamp fail closed. A persisted index row remains
+an untrusted candidate after process restart and must be reverified from byte zero before minting a
+fresh in-memory proof.
+
+A same-inode prefix rewrite followed by suffix growth violates this trust boundary and is
+indistinguishable from a valid append through portable path, inode, timestamp, and size metadata. A
+live warm anchor can therefore skip rewritten earlier records. A new process verifies the current
+bytes from zero. Detecting this mutation while retaining bounded warm I/O requires future
+writer-authenticated generation lineage. The Reference projection injects this reader behind its
+private page-reader seam; Core subscriptions and the authoritative from-zero reader remain
+storage-neutral.
+
+`ReferenceEventOffsetIndex` is the internal warm-read coordinator for those anchors. It retains the
+first verified record, sparse anchors at fixed byte or record strides, and the newest verified
+record as strong process-local references. One per-source lock single-flights cold construction;
+different event logs remain independent. A page scan stages only lightweight stride-selected
+candidates plus its newest safe-prefix candidate. It mints and publishes anchor capabilities after
+the captured snapshot passes final verification. Path replacement, committed-prefix truncation,
+physical shrink, a detected same-size rewrite, or an expired proof clears the derived state and
+permits one authoritative from-zero retry. Committed event-log corruption remains authoritative and
+propagates unchanged.
+
+The index retains at most 128 source slots by default. Its `max_sources` constructor setting defines
+that hard retained-slot capacity; `RunnerBackend.event_index_max_sources` configures the owned
+Reference instance. Page reads pin admitted slots before taking the per-source I/O lock, so
+concurrent readers for one retained cold source share one construction. A miss replaces the
+least-recently-used idle slot. When every retained slot is active, a miss reads one authoritative
+snapshot from byte zero without creating a slot or anchor capabilities. This bypass preserves event
+delivery and the hard metadata bound. It uses an independent snapshot, and another read can repeat
+that cold work until capacity becomes available. Capacity zero routes every read through this
+authoritative uncached path.
+
+`cache_stats()` exposes retained sources, pins, page-read hits and misses, idle-slot evictions, and
+saturated bypasses. `stats()` and `invalidate()` create no slots and leave recency unchanged. An
+evicted source verifies from byte zero on its next read, so deployments size `max_sources` for the
+hot polled-source working set. Source capacity bounds retained slot and capability metadata;
+per-source sparse-anchor density remains governed by the byte and record strides.
+
+A new process starts with an empty offset index. Its first relevant read verifies JSONL from byte
+zero while rebuilding sparse anchors; later pages and append-only-conforming same-process appends
+extend from the retained tail. Persisting candidate offsets cannot reduce that required verification
+under the current process-local proof contract. Constant-work restart remains coupled to the future
+writer-authenticated generation lineage.
+
+Each `RunnerBackend` owns one index and injects its page reader into `RunProjectionService`. Root
+events, authorized descendant events, and diagnostics share that instance. Authorization and
+descendant-lineage validation complete before cache admission. Backend JSON, SSE, Studio transports,
+`SequenceCursor`, Last-Event-ID resume, heartbeat emission, and terminal final draining continue to
+consume the same `{events, next_seq, has_more}` page shape. Backend shutdown leaves the cache alone
+because shutdown is a non-terminal operational stop and Studio ingress can still be active; bounded
+capacity supplies the process-lifetime memory control.
 
 `SequenceCursor` and `EventSubscription` turn that inclusive page API into a reusable next-sequence
 subscription. A cursor advances only after an event is presented, suppresses replayed sequences,
@@ -1140,14 +1222,19 @@ competing input.
   each run (re-issuing gateway tokens from the signing key, **re-provisioning the base workspace**
   is the deployment's job), `restore()`s the loop with the store's blobs, re-enqueues durably-saved
   follow-up messages, and resumes.
-- The experimental v0.18 DBOS activation-recovery profile has a narrower operational scope. One
+- The experimental v0.19.2 DBOS activation-recovery profile has a narrow operational scope. One
   stable executor slot has one active process; a restart reuses the same executor identity and
-  application version after the prior process terminates or is fenced. DBOS schedules and retries
-  one finite activation. The configured `CheckpointStore` remains authoritative for checkpoint
-  sequence, input deduplication, the committed boundary receipt, suspension, and terminal meaning.
-  The profile scope covers same-slot finite-activation recovery. The Reference backend, terminal
-  artifact finalization, HTTP, Studio, and arbitrary-host takeover remain separate. Portable
-  recovery semantics remain unchanged.
+  application version after the prior process terminates or is fenced. One private Reference host
+  owns a captured process-global DBOS runtime. Its private control and run participants register
+  distinct workflow families, preflight their queue names, and contribute one aggregate listener
+  set before one launch. The host registers participant queue objects after launch, then opens
+  shared admission. The participants also share host drain and shutdown. DBOS schedules and retries
+  finite control-dispatch and run-resume activations. The configured `CheckpointStore` remains
+  authoritative for checkpoint sequence, input deduplication, committed boundary receipts,
+  suspension, and terminal meaning. The profile scope covers same-slot finite-activation recovery
+  and private lifecycle composition. The Reference backend, terminal artifact finalization, HTTP,
+  Studio, product routing, and arbitrary-host takeover sit outside this scope. Portable recovery
+  semantics remain unchanged.
 
 **Assumption (workspace):** the agent workspace is not durable; on restore the
 deployment re-provisions the base (re-clone/re-mount) and the checkpoint re-applies
@@ -1163,8 +1250,9 @@ by-value `messages` in the checkpoint are the load-bearing conversation record).
 
 ## Legacy Reference Production Hardening
 
-This section describes the legacy `RunnerBackend` lease/watchdog profile. The DBOS Reference path
-does not compose these services. The core never auto-recovers.
+This section applies to the legacy `RunnerBackend` lease/watchdog profile. The DBOS Reference
+profile has a private host-owned runtime lifecycle and no lease/watchdog stack. Core recovery
+requires explicit host orchestration.
 
 ### Failure surfacing & bounded recovery
 

{monoid_agent_kernel-0.19.1 → monoid_agent_kernel-0.19.2}/docs/DBOS_REFERENCE.md

@@ -1,13 +1,15 @@
 # DBOS Reference Activation-Recovery Profile
 
-Status: experimental v0.18.0 Reference profile. The optional extra pins the validated DBOS 2.26
-minor line. DBOS owns the operational execution of one finite activation: admission, per-run
-serialization, retry, same-slot workflow recovery, and the workflow result. The Core-defined
-`CheckpointStore` owns the portable semantic state, including input deduplication, the committed
-boundary receipt, suspension, and terminal meaning.
+Status: experimental v0.19.2 Reference profile. The optional extra pins the validated DBOS 2.26
+minor line. DBOS owns finite-activation admission, participant-local per-run serialization, retry,
+same-slot workflow recovery, and workflow results. The private hosted composition adds one shared
+process-runtime lifecycle for control and run participants. The Core-defined `CheckpointStore`
+owns portable semantic state, including input deduplication, committed boundary receipts,
+suspension, and terminal meaning.
 
-This profile is a recovery interoperability proof. Its v0.18 scope covers one finite activation;
-`RunnerBackend`, Studio, and production cutover remain separate.
+This profile is a recovery interoperability proof. Its v0.19.2 scope covers finite control-dispatch
+and run-resume activations plus private shared-host ownership for those hosted workflows.
+`RunnerBackend`, Studio, product routing, and production cutover sit outside this profile.
 
 Install the profile with:
 
@@ -16,7 +18,7 @@ python -m pip install "monoid-agent-kernel[reference-dbos]"
 ```
 
 Importing `monoid_agent_kernel` or `monoid_agent_kernel.reference.dbos` stays lazy. DBOS loads when
-`DbosRunDriver` or `DbosControlPlane` is constructed.
+a standalone `DbosRunDriver` or `DbosControlPlane`, or the private runtime host, is constructed.
 
 ## Boundary
 
@@ -105,10 +107,18 @@ driver.enqueue_resume(command)
 receipt = driver.wait_for_receipt(command)
 ```
 
-`DbosControlPlane` remains the isolated authenticated, credential-sanitizing transport experiment
-from the earlier control-plane spike. v0.18 evaluates it separately from `DbosRunDriver`. The
-legacy Reference command inbox remains a separate valid multi-instance assembly. Shared DBOS host
-composition belongs to a future architecture decision.
+The exported `DbosControlPlane` and `DbosRunDriver` remain standalone experimental entry points.
+Their Reference-private hosted forms register with one private runtime host. The host constructs
+one captured DBOS runtime and registry, aggregates the participants' distinct versioned queues and
+stable workflow names under one shared namespace, launches once, and owns shared admission and
+shutdown. Every hosted participant must request the same database URL, application name,
+application version, executor ID, and shutdown grace. Queue and retry settings remain
+participant-local.
+
+The control and run queues serialize their own partitions independently. Cross-surface per-run
+serialization and control-to-run semantic routing require product integration. The host and
+participant-registration factories are private Reference implementation details. The legacy
+Reference command inbox remains a separate valid multi-instance assembly.
 
 ## Stable executor slot
 
@@ -125,7 +135,7 @@ excludes Conductor. A later multi-host requirement can add a narrow Reference re
 coordinator that reassigns eligible DBOS work while preserving checkpoint sequence and slot
 fencing. That coordinator stays smaller than a general orchestration control plane.
 
-SQLite is the checked development and single-host acceptance database. v0.18 validates that
+SQLite is the checked development and single-host acceptance database. v0.19.2 validates that
 configuration only. DBOS recommends PostgreSQL for production system-database deployments;
 PostgreSQL process qualification and any broader takeover contract belong to a future milestone.
 
@@ -180,10 +190,17 @@ then resumes the still-pending DBOS workflow.
 
 ## Runtime and version lifecycle
 
-DBOS owns a process-global runtime and workflow registry. Reference DBOS components claim one
-process owner before workflow registration. `close()` stops admission, waits for active workflows,
-verifies the DBOS active-workflow set, and releases ownership. A grace timeout requires process
-termination.
+DBOS owns a process-global runtime and workflow registry. Standalone Reference DBOS components
+claim one process owner before workflow registration. In the private hosted composition, control
+and run participants register before launch and share an exact host identity. The host registers
+both workflow families, preflights both queues, installs one aggregate listener set, launches the
+captured runtime once, registers both queues, and then opens admission.
+
+Identity-scoped hosted submissions require a clean external call context; an ambient DBOS workflow
+context is rejected before durable enqueue. Shared close stops host and participant admission,
+drains admitted facade calls, destroys the captured runtime once under one deadline, proves both
+participants drained, clears DBOS globals, and releases process ownership. Uncertain launch,
+drain, or shutdown fences the host and requires process termination.
 
 Finite workflows keep version-drain pressure bounded. A deployment retains compatible workflow
 code for pending work, keeps `application_version` stable across a slot restart, and changes the
@@ -191,7 +208,7 @@ version when workflow operation order or durable input/result compatibility chan
 
 The exported resume-command and run-receipt version constants describe this experimental
 Reference profile only. They are excluded from the stable Core compatibility inventory and carry
-no mixed-version rolling-reader guarantee in v0.18. Drain pending workflows before deploying an
+no mixed-version rolling-reader guarantee in v0.19.2. Drain pending workflows before deploying an
 incompatible record or operation-order change.
 
 Official references:
@@ -202,7 +219,7 @@ Official references:
 - [Workflow recovery](https://docs.dbos.dev/production/workflow-recovery)
 - [Workflow code upgrades](https://docs.dbos.dev/python/tutorials/upgrading-workflows)
 
-## v0.18 status and non-goals
+## v0.19.2 status and non-goals
 
 Completed vertical-slice gates:
 
@@ -215,16 +232,27 @@ Completed vertical-slice gates:
    finite-activation workflow result copied from the committed checkpoint receipt.
 4. Core checkpoints carry the exact portable suspension observation, and `AgentLoop.release_parked`
    closes process resources without finalizing the run.
+5. The DBOS 2.26 adapter binds workflow registration, identity-scoped workflow access, queues,
+   launch, and shutdown to one captured runtime and verifies process-global ownership.
+6. The private runtime host aggregates hosted control and run workflows under one listener set,
+   launch, admission, drain, and shutdown lifecycle. Hosted control recovery and hosted run
+   recovery pass same-slot process-restart acceptance.
+7. Run recovery covers effect-committed and boundary-committed crashes across standalone,
+   hosted, and standalone-to-hosted transitions. Real composition acceptance proves one runtime,
+   two queues, one launch, one destroy, both participant receipts, and fresh replacement ownership.
 
-The v0.18 profile deliberately stops at that vertical slice. Its non-goals are:
+The v0.19.2 profile stops at that Reference-private vertical slice. Its non-goals are:
 
 - replacing `RunnerBackend`, its HTTP facade, or Studio;
-- composing the control-plane experiment and run driver into a production host;
+- publishing the private runtime host or participant-registration seam as a supported product API;
+- automatic standalone-component composition or control-to-run semantic routing;
 - migrating submission, task-result, pause, cancel, status, or terminal artifact projection;
 - claiming one physical write for proposal, metrics, `run.finished`, or other rebuildable views;
 - PostgreSQL production qualification, rolling upgrades, or arbitrary-host takeover;
 - retiring the accepted durable Reference command-inbox workstream.
 
-These items sit outside the v0.18 release scope. A future DBOS milestone must first choose one
-explicit authority model. The portable model keeps `CheckpointStore` authoritative for
-boundary/terminal receipts and other semantic state while DBOS remains an activation scheduler.
+These items sit outside the v0.19.2 release scope and require separate product-integration design
+review. The private host owns DBOS lifecycle. Hosted participants add no `LeaseStore`,
+`CommandStore`, `RecoveryService`, or watchdog lifecycle. `CheckpointStore` remains authoritative
+for boundary and terminal receipts and other portable semantic state while DBOS remains the
+activation scheduler.

{monoid_agent_kernel-0.19.1 → monoid_agent_kernel-0.19.2}/docs/EMBEDDING.md

@@ -64,11 +64,11 @@ with tenant routing, multiple API instances, external workers, callbacks, and du
 
 ## Choose one hosted assembly
 
-| Assembly | v0.18 position | Operational owner | Recovery scope |
+| Assembly | v0.19.2 position | Operational owner | Recovery scope |
 |---|---|---|---|
 | Product-owned runtime | Production integration target | The product's scheduler and worker control plane | Defined and qualified by the product |
 | Reference inbox assembly | Runnable Reference example and CI-qualified hosted golden path | `RunnerBackend`, `LeaseStore`, `CommandStore`, `RecoveryService`, and watchdog | Shared-store stale-owner claim demonstrated with SQLite |
-| Optional DBOS activation-recovery profile | Experimental Reference recovery proof | DBOS owns finite activation admission, serialization, retry, and same-slot workflow recovery | Same `executor_id` and `application_version` after a fenced restart |
+| Optional DBOS activation-recovery profile | Experimental private Reference composition proof | One private host owns the process-global DBOS runtime and hosted control/run lifecycle | Same `executor_id` and `application_version` after a fenced restart; hosted control and run recovery are acceptance-tested |
 
 The hosted golden path uses owner-local Reference submission together with the durable inbox for
 post-submission status, task-result, and approval commands. It also covers event projection and
@@ -76,12 +76,18 @@ tenant usage through one executable facade. `submit_run()` has no durable client
 the product edge owns idempotent initial-submission admission and routes each accepted submission
 to the selected owner. Integrators place this Reference fixture behind their own product API.
 
-The optional DBOS profile covers one finite resume activation. `CheckpointStore` remains the
-semantic authority, and the DBOS workflow result copies the committed boundary receipt. Its v0.18
-scope excludes `RunnerBackend` replacement, Studio integration, terminal artifact projection,
-PostgreSQL production qualification, rolling upgrades, and arbitrary-host takeover. Conductor is
-outside this profile. The isolated DBOS control experiment and run driver also remain separate.
-See [DBOS_REFERENCE.md](DBOS_REFERENCE.md) for the exact verified invariant and non-goals.
+The optional DBOS profile covers finite control-dispatch and run-resume activations.
+`CheckpointStore` remains the run-semantic authority, and each run-resume workflow result copies
+its committed boundary receipt. Control workflows return a versioned, credential-sanitized
+`CommandReceipt` after dispatch. Private hosted control and run participants share one captured
+runtime, listener set, launch, admission, drain, and shutdown lifecycle while retaining distinct
+partitioned queues. The exported standalone components remain individual experimental entry
+points.
+
+The v0.19.2 scope excludes `RunnerBackend` replacement, hosted-golden-path routing, Studio and
+terminal-projection migration, PostgreSQL production qualification, rolling upgrades,
+arbitrary-host takeover, and Conductor. See [DBOS_REFERENCE.md](DBOS_REFERENCE.md) for the exact
+verified invariant and non-goals.
 
 ## Golden path A: embedded/local product
 
@@ -228,10 +234,11 @@ one transactional command store. A fresh backend can call `recover_runs()` and s
 after an atomic stale-owner claim. Queue limits and claim TTLs bound durable command admission and
 recovery. The bundled SQLite composition remains a single-host Reference fixture.
 
-For the experimental DBOS profile, a supervisor fences the previous process and restarts the same
-stable executor slot with the same application version. DBOS resumes pending finite activations;
-the checked checkpoint remains canonical for semantic state. The profile contains no Reference
-lease, command inbox, recovery service, or watchdog.
+For the experimental DBOS profile, the private host is the sole DBOS lifecycle authority in one
+process. A supervisor fences the previous process and restarts the same stable executor slot with
+the same application version. DBOS resumes pending finite activations; the checked checkpoint
+remains canonical for semantic state. The profile contains no Reference lease, command inbox,
+recovery service, or watchdog lifecycle.
 
 Every durable family has a versioned codec and compatibility-ledger entry. Upgrade in this order:
 
@@ -244,7 +251,7 @@ Every durable family has a versioned codec and compatibility-ledger entry. Upgra
 Run `python -m pytest -q tests/test_compatibility_ledger.py`, then follow the mixed-version and
 rollback procedures in [COMPATIBILITY.md](COMPATIBILITY.md). DBOS workflow inputs, results, executor
 identity, and application-version operation remain governed by the experimental profile document;
-v0.18 makes no production rolling-upgrade claim for that profile.
+v0.19.2 makes no production rolling-upgrade claim for that profile.
 
 ## Streaming and cursor ownership
 
@@ -305,8 +312,10 @@ For tool approvals, render the sanitized durable task request, preserve the task
 decision through the callback-scoped path. Record the approver and reason. Execute the original
 durable request after approval.
 
-The v0.18 `DbosControlPlane` is an isolated transport experiment. It does not supply the hosted
-facade used by this golden path and does not compose with `DbosRunDriver`.
+The exported `DbosControlPlane` is an isolated transport experiment outside the hosted golden
+facade. Its private hosted form composes with the private hosted run participant under one
+Reference runtime host. Public product routing across those participants sits outside the v0.19.2
+proof.
 
 ## Gateway credentials and security
 
@@ -381,8 +390,9 @@ Before production traffic:
 7. complete [security/PRODUCTION_CHECKLIST.md](security/PRODUCTION_CHECKLIST.md).
 
 For the Reference inbox fixture, run `tests/test_backend_command_inbox.py` and its shared-store
-recovery tests. For DBOS evaluation, install `reference-dbos`, run its focused model/driver/process
-tests, and apply the scope limits in [DBOS_REFERENCE.md](DBOS_REFERENCE.md).
+recovery tests. For DBOS evaluation, install `reference-dbos`, run the owned-runtime, shared-host,
+hosted-control, hosted-run, and process-restart suites, and apply the scope limits in
+[DBOS_REFERENCE.md](DBOS_REFERENCE.md).
 
 `tests/test_examples.py` imports and executes both golden paths. Contract, Helper Kit, and Reference
 facade drift therefore fails CI at the same integration points shown here.