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.

Visual understanding · Workflow diagrams

These are information-flow diagrams, not import graphs. Arrows mean a caller passes or records information; they do not imply automatic dispatch. Contracts own exact field names and bounds; the build review owns current acceptance.

Provider diagnostics

Input supplier: Caller holding a retained provider result. Input: Original structured provider result and explicit source attribution. Provider diagnostics: Project bounded observations without changing the original result. Output: Historical diagnostics and explicit missing detail. Consumer: Caller displaying recorded provider outcomes. Boundary: Does not infer causes from stderr, authenticate evidence, permit retries or establish current provider availability.

Feed it: Original structured provider result and explicit source attribution. Supplier: Caller holding a retained provider result.

Use its result: Historical diagnostics and explicit missing detail. Consumer: Caller displaying recorded provider outcomes.

Boundary: Does not infer causes from stderr, authenticate evidence, permit retries or establish current provider availability.

Human guide · Exact contract · Open full-size diagram

Provider event delivery

Input supplier: Separately commissioned subscription caller. Input: Original notification, allowance, current permission and fixed deadline. Provider event delivery: Deliver one retained notification through bounded reconciled attempts. Output: Transport receipt, proven terminal result or unknown contact. Consumer: Caller inspecting notification delivery. Boundary: A receipt does not prove processing or domain work. Loopback proof does not qualify public DNS, credentials or production delivery.

Feed it: Original notification, allowance, current permission and fixed deadline. Supplier: Separately commissioned subscription caller.

Use its result: Transport receipt, proven terminal result or unknown contact. Consumer: Caller inspecting notification delivery.

Boundary: A receipt does not prove processing or domain work. Loopback proof does not qualify public DNS, credentials or production delivery.

Human guide · Exact contract · Open full-size diagram

Proposal ownership

Input supplier: Caller under qualified authority fence. Input: Immutable generation, source pins, RulePin and expected version. Proposal ownership: Keep original proposal and permanent first-offer ownership. Output: Versioned proposal history and unresolved effect ownership. Consumer: Guidance receiver; notification ownership caller. Boundary: First offer prevents replacement even after expiry or lost reply. Includes bounded notification ownership, but no sender or inbox.

Feed it: Immutable generation, source pins, RulePin and expected version. Supplier: Caller under qualified authority fence.

Use its result: Versioned proposal history and unresolved effect ownership. Consumer: Guidance receiver; notification ownership caller.

Boundary: First offer prevents replacement even after expiry or lost reply. Includes bounded notification ownership, but no sender or inbox.

Human guide · Exact contract · Open full-size diagram

Guidance acceptance

Input supplier: Caller with one original offered generation. Input: Original Guidance command, ownership history, registry and current fence. Guidance acceptance: Apply or inspect the original command under current permission. Output: Actual Guidance revision, historical witness or refused/unknown outcome. Consumer: Provider Guidance tools and caller. Boundary: The domain commit is acceptance. No release of ownership, replacement, automatic retry or live provider qualification.

Feed it: Original Guidance command, ownership history, registry and current fence. Supplier: Caller with one original offered generation.

Use its result: Actual Guidance revision, historical witness or refused/unknown outcome. Consumer: Provider Guidance tools and caller.

Boundary: The domain commit is acceptance. No release of ownership, replacement, automatic retry or live provider qualification.

Human guide · Exact contract · Open full-size diagram

Provider events

Input supplier: Trusted committed Branch health event. Input: Exact source event, scoped permission, Product filter and asOf. Provider events: Project one bounded notification from a committed fact. Output: Notification identity, source digest and detail handle. Consumer: Caller-owned notification host. Boundary: Pure projection supplies no delivery, deduplication or authentication. Host must prove commit and permission.

Feed it: Exact source event, scoped permission, Product filter and asOf. Supplier: Trusted committed Branch health event.

Use its result: Notification identity, source digest and detail handle. Consumer: Caller-owned notification host.

Boundary: Pure projection supplies no delivery, deduplication or authentication. Host must prove commit and permission.

Human guide · Exact contract · Open full-size diagram

Provider subscriptions

Input supplier: Authenticated caller-owned host. Input: Private store, current authority, callback connector, clock and nonce. Provider subscriptions: Keep subscription lifecycle and verify a bounded signed challenge. Output: Subscription wire receipt or fixed refusal. Consumer: Existing host and Provider Events RPC. Boundary: Verification contacts are bounded; uncertain debits remain. Sends no application notifications; no live host is qualified.

Feed it: Private store, current authority, callback connector, clock and nonce. Supplier: Authenticated caller-owned host.

Use its result: Subscription wire receipt or fixed refusal. Consumer: Existing host and Provider Events RPC.

Boundary: Verification contacts are bounded; uncertain debits remain. Sends no application notifications; no live host is qualified.

Human guide · Exact contract · Open full-size diagram

Provider events RPC

Input supplier: Authenticated request router. Input: Bounded list/subscribe/unsubscribe request and outside-params identity. Provider Events RPC: Route one request to the existing subscription host. Output: Approved wire result or fixed wire error. Consumer: Caller-owned MCP request/response channel. Boundary: No HTTP listener, retry or mutation replay cache. Request ID reuse never proves the original effect did not happen.

Feed it: Bounded list/subscribe/unsubscribe request and outside-params identity. Supplier: Authenticated request router.

Use its result: Approved wire result or fixed wire error. Consumer: Caller-owned MCP request/response channel.

Boundary: No HTTP listener, retry or mutation replay cache. Request ID reuse never proves the original effect did not happen.

Human guide · Exact contract · Open full-size diagram

Provider guidance tools

Input supplier: Authenticated caller-owned tool host. Input: Original proposal identity and actor/Product context. Provider Guidance tools: Route inspect or apply to the existing Guidance receiver. Output: Canonical structured outcome and same JSON text. Consumer: Caller-owned MCP tool channel. Boundary: No model grants permission. Possibly-recorded apply stays uncertain; no new command or automatic retry follows a tool error.

Feed it: Original proposal identity and actor/Product context. Supplier: Authenticated caller-owned tool host.

Use its result: Canonical structured outcome and same JSON text. Consumer: Caller-owned MCP tool channel.

Boundary: No model grants permission. Possibly-recorded apply stays uncertain; no new command or automatic retry follows a tool error.

Human guide · Exact contract · Open full-size diagram

Source: docs/explanation/visual-provider.md