Factory docs, home
Page navigation

Pre-release documentation. Proposed designs are labelled in the page; acceptance evidence is maintained in the build review. Local paths appear as placeholders. Current state: Build review.

Owner-commissioned integration design, 30 September 2026. Bounded EV1 projection and EV2 subscription lifecycle modules exist; the live MCP HTTP host and application delivery remain unimplemented. This extends the independent composition programme through an optional transport adapter. All 38 epics remain open; existing model commissions and D4/Knowledge boundaries remain. The candidates below were merged on 1 October 2026 after an Opus 5.5 review; they have no consumer yet, and live hosting needs an owner decision.

The bounded EV1 implementation draft projects one real committed Branch health poll through explicit caller-owned source pins and permission values. Separate independent source/package review passed; 1,885 coordinator integration checks passed; separate integration delta review passed. The bounded EV2a private host candidate implements subscription lifecycle and signed verification. The original EV2a integration passed 1,976 full and 198 package/docs checks with independent combined package review. Its native-data correction passed independent source/package review, and the corrected stack at 6f4ff02 passed 2,045 full checks; Root's earlier 2,121-check combined full run and independent same-package Journal/EV2/notification-ownership physical proof passed; final publication review, CI/Fable and live qualification remain open. Application delivery, replay and live host/connector qualification below remain unimplemented.

The thin EV2b method adapter and two EV4a Guidance tools now have separately accepted corrected source and private packages. The earlier 2,121-check full run includes the installed RPC, Guidance-tools and receiver consumers. Separate independent same-package physical qualification covers their Journal, EV2 and notification-ownership dependencies only. CI/Fable and live qualification remain open. The adapter routes three existing host methods; the tools inspect/apply one original Guidance offer through the actual receiver. Neither is a live MCP listener, application sender or generic job dispatcher.

What the standard gives us

OpenAI MCP Events lets an authenticated Factory MCP server send subscribed updates to ChatGPT. The supported profile requires MCP 2.0, version 2026-07-28, and webhook delivery. Discovery, subscribe and unsubscribe have dedicated methods. ChatGPT does not support the draft's polling, streaming or gap/terminated notifications. Callback verification, persistent subscription ownership, expiry and access revocation belong to the server. A successful HTTP response confirms receipt; subsequent agent processing is asynchronous. The body limit is 256 KiB; retries retain the event identity. These are transport facts, not proof of a completed Factory job.

The underlying MCP draft, pinned at 6682596, also describes other delivery modes and opaque cursors. It remains a draft. Treat the OpenAI-supported subset as a reviewed profile, rather than assume every client implements the entire proposal. A different provider needs its own observed capability/profile evidence.

Where it fits

The first useful direction is Factory → subscribed assistant: a committed, scoped fact changes; the adapter sends a small attributable notification; the assistant can retrieve authorised detail and follow the user's commissioned response. A review request, changed repair evidence or a decision becoming due could eventually wake useful work. Those event families are proposed until their owning domain supplies a durable occurrence and read contract.

The reverse direction is a separate assistant → Factory tool boundary. A tool call requests a read or an admitted domain command. It must pass the same current scope, authority, Budget, input, replay and evidence checks as another caller. An event payload does not contain executable instructions, credentials, shell fragments or a grant. The callback's success cannot grant a publish/release permission or supply an independent Verdict.

BoundaryOwnsCannot establish
Domain ModuleState decision, immutable source event, actual occurrence timeDelivery or external work completion
Shared delivery facilitiesStable occurrence/consumer identities, bounded ownership and progressSource truth or permission to execute a different command
MCP notification adapterSupported profile, authorised catalogue/filters, subscription lifecycle, signed deliveryModel qualification or accepted domain work
Assistant hostReceipt and its commissioned reactionFactory acceptance solely by saying it ran
Factory tool/job boundaryCurrent admission, durable command receipt, attributable result and independent verificationA broader grant from callback text
IntelligenceDeclared task, exact model/effort/transport, qualification and output checkA model identity inferred from plugin or reviewer wording

Existing Intelligence is a pure registry/selector. An MCP webhook is not an inference transport and must not be added to its model transport union. ChatGPT's receipt does not expose the exact request-count, pinned model or independently checked task result required by the current Producer contract. Any future host-mediated model work needs a separate measured commission and reviewed task protocol; absence creates an unavailable disposition, never a silent provider substitution.

Keep one delivery responsibility

CommandJournal.execute already commits a decision, receipt, events and pending outbox entries atomically. readPendingOutbox supplies a bounded page; it implements neither dispatch nor acknowledgement. Its sequence is local to a store and records no universal occurrence timestamp. Do not export the raw outbox as a ready event service.

Reuse the proposed T36 delivery contract for shared ownership/replay where its semantics fit. Keep a notification-specific transport outcome beside domain receiver acceptance:

  • Webhook receipt: the remote callback accepted bytes for processing.
  • Domain acceptance: an independently attributable receiver stored the exact command identity and payload digest.
  • Effect/result: the requested work completed with its own evidence and reconciliation state.

These records remain separate. A 2xx callback cannot be cast to T36's accepted-command result, a ProducerReceipt, a release Receipt or a successful Assessment. Repeated notification delivery may wake repeated tool requests; only the domain's idempotent command contract prevents duplicate effects. Notification retries never mint a fresh logical job or renew its Budget.

The protected D4/R7 candidate at 42d2700 composes authored Candidates and repository verification; it does not supply a generic event dispatcher. Preserve its files and receipts. Resolve shared delivery ownership before implementing another durable attempt ledger. E37 intake owns authenticated external observations; receiving source events is separate from this Factory-to-assistant notification direction.

Proposed payload and scope contract

Expose a small allowlisted catalogue, filtered server-side by the authenticated principal and logical Product/scope. Each future definition declares a versioned name, exact arguments, payload schema and supported delivery profile. A subscription identifies its principal, permitted event/filter set and callback; a caller cannot enumerate another Product or opt into a broader stream through an arbitrary filter.

Project approved domain fields into a bounded payload. Prefer logical IDs, immutable source/record references, status and a permitted detail-read key. Exclude raw journal rows, command payloads, personal notes, checkout paths, provider responses and arbitrary source URLs. Detail reads apply current authorisation and redaction again; an event reference is not a bearer credential. This also keeps notifications useful when a host batches them or only displays a summary.

Bind the occurrence to a persistent producer/store namespace, domain event identity and versioned projection. Never use a SQLite sequence alone as a global ID. Retries preserve the same occurrence and payload bytes; conflicting bytes under an immutable identity refuse. Per-subscription delivery identity is separate, so one audience's receipt does not acknowledge another's delivery.

Use an actual domain occurrence timestamp. Where the journal has no such field, a mapper must obtain a validated, pinned domain record or refuse that event family; it must not invent occurrence time from dispatch time. A timestamp, sequence or notification arriving last cannot prove causality, current health or an observed release.

Breaking payload changes receive a new event name/profile with an explicit migration. Old retained notifications preserve their interpretation. Missing records, revoked detail access, expired references and unsupported profile versions return typed refusals or unknown coverage; they do not become an empty healthy stream.

Subscription, secrets and delivery

The bounded EV2 API takes a caller-owned private transactional store, current authority and a separately qualified verification connector. Its private state retains signing material, granted expiry, principal/filter binding, callback verification and lifecycle epochs; domain journals, prompts and public evidence contain no secrets. The caller supplies store-wide and authority fences, restart-safe persistence and bounded cleanup. Renewal and unsubscribe are implemented; application delivery must separately recheck the current generation and access. A reachable authenticated MCP HTTP host and production connector qualification remain future work.

Implement callback transport using the documented verification and Standard Webhooks contract. It must validate and pin public destination addresses at each actual connection, retain the hostname for TLS, block redirects and bound time/body/attempts. A URL allowlist or preliminary DNS lookup alone is insufficient. No callback-supplied address can reach local Factory stores or another tenant. Library/SDK choice, versions and connection behaviour need their own evidence; this plan commissions no install or live endpoint.

Delivery ownership binds subscription generation, profile, payload digest and current permission. Recheck those pins immediately before dispatch; refresh/rotation/removal races cannot silently deliver under a replaced identity. Receipt, transient failure, permanent refusal and unknown acknowledgement are distinct. A lost acknowledgement may repeat the same deduplicable notification within its bounds; it never authorises repeating the underlying work.

Advance replay cursors only through accounted contiguous progress for that subscription. A newer receipt cannot skip an older pending occurrence. Cursors remain opaque and store/profile-bound; a replaced store or unavailable history requires explicit reconciliation. Since ChatGPT omits the draft's gap/termination controls, do not send them or infer recovery: expose missing coverage through an authorised read/status contract and resubscription policy. A non-replayable profile declares its interruption limits.

Prevent feedback loops with causal/root identity, originating command references, rule/target deduplication, bounded fan-out/depth and a fixed per-occurrence allowance. Meaningless unchanged notifications should not consume inference capacity. Do not suppress a later independent regression merely because its text resembles an earlier repair.

Alignment with our values

The initial use case should close a specific response gap, such as attributable review feedback reaching a bounded draft-fix job; message volume is not customer value. Earned trust means checking source identity and recording receipt separately from verified outcomes. Recoverable change means replayable notifications, preserved unknown effects and explicit reconnect gaps. Accountable autonomy means commissioned reactions can advance without new routine gates while current authority still applies.

Keep the adapter replaceable and independently consumable with caller-owned storage, secret and transport ports. A host without event support retains explicit on-demand reads; imports start no listener or subscription. This supports useful simplicity and independent composition without introducing a second workflow engine. Notifications can carry Plumb's clear, warm presentation, while failures, spend, revocation and uncertainty stay plain.

Bounded implementation packets

PacketUseful resultRequired proof
EV1 profile and projectionOne real domain occurrence becomes a typed, redacted notification and authorised detail referenceActual source records, stable cross-store identity, timestamp provenance, filters, bounds, immutable replay and passive external package consumer
EV2 authenticated subscription hostScoped discovery and durable subscribe/refresh/unsubscribe against a disposable receiverCurrent access, callback challenge, secret isolation/rotation, restart, expiry/revocation races and no private/redirect destination
EV3 notification deliveryBounded notifications with explicit receipt/unknown states and honest cursorsCrash before/after send, lost/late acknowledgement, duplicates/order, permanent refusals, contiguous progress and substitute receiver; no claimed exactly-once effects
EV4 tool/job compositionA subscribed fact requests one authorised existing job through the same public command contractReceipt versus acceptance/result separation, repeated tool calls, cancellation/revocation, fixed Budget, unqualified-model refusal and loop/regression probes

EV1 freezes the first actual event family and public contract before source work; proposed review/job names are not advertised APIs. EV2/EV3 reuse shared delivery facilities only after their ownership and semantics are proved. EV4 depends on the chosen complete Workflow or existing admitted command, not a fictional generic dispatch tool. Count shared delivery once in T36, and estimate incremental adapter work after EV1 exposes the real closure.

Every implementation needs an actual private tarball consumer, alternate permitted collaborators, frozen-source independent review and generated docs/checks. A live ChatGPT subscription additionally needs an authenticated reachable host, current grants, real callback and tool/effect readback. Local fixtures cannot prove host availability, provider qualification, publication or customer benefit. This design authorises no deployment, purchase, credential widening or merge.

Source: docs/provider-events.md