Developer Manual

Architecture and responsibilities

Understand the host, packages, provider, verifier, and authority boundaries.

The Developer Manual is for engineers integrating AnswerUp into an application they operate. It complements Concepts, which explains the model, and the API Reference, which records exact package declarations.

The system boundary

The host application receives a request, supplies trusted identity and business context, searches its authoritative systems, and renders the result. AnswerUp does not perform provider or verifier I/O and does not own the host’s business database.

Component	Role	Owns	Does not do
Host application	Coordinates transport, domain interpretation, context, policy, adapters, persistence, and presentation	Business meaning, credentials, tenant scope, durable records	Treat model output or provider acknowledgment as truth
Proposing system	Produces a bounded proposal	Intent supplied by the user or workflow	Authority, authorization, or effect truth
Framework/channel adapter	Maps an ingress or tool call into host input	Transport parsing and channel identity	Widen trusted context or authorize an action
`@answerup/actions`	Protected-action composition and bounded result projection	The package’s public action contract	Hosted execution or durable storage
`@answerup/runtime`	Process-local orchestration, execution, verification, reconciliation, and projection; durable verifier-only rehydration through the accepted recovery authority	Runtime handles, lifecycle sequencing, and verifier-only read-back	Hosted durability, automatic recovery, exactly-once execution, or provider redispatch
`@answerup/core`	Grounding, authorization provenance, identities, lifecycle, effect resolution, and claim permission	Core semantic artifacts	Provider calls, business searches, or persistence
Provider adapter	Attempts the requested external mutation	Provider credentials, request mapping, acknowledgment	Independent proof of success
Independent verifier	Reads the authoritative system and reports bounded evidence	Verifier credentials and read policy	Guessing, self-verification, or mutation
Authoritative system	Owns business state	Records and final state	AnswerUp lifecycle semantics
Durable action record	Host-owned record of the lifecycle	Retention, access control, and recovery data	Becoming business authority
Trace/conformance tooling	Connects bounded observations or evaluates fixtures	Tooling output and evidence	Becoming effect truth or production certification

Lifecycle crosswalk

The Semantic Integrity Chain is the authority and claim-semantic model. The Runtime

operational lifecycle is its implementation and control-flow projection. They are

complementary abstraction layers, not competing lifecycle definitions or a

one-to-one list of software functions.

Semantic Integrity Chain	Runtime operational relationship	Meaning and boundary
Evidence	Admission and trusted context; grounding inputs	Bounded request data, source observations, identity, tenant or scope, and other inputs the host admits for grounding. Supplied evidence does not become authority merely because it was received.
Proposal	Admission and trusted context	The admitted request or operation to evaluate. The proposing system supplies intent, not authorization or effect truth.
Grounding	Grounding	The host resolves the exact referent using trusted context and authoritative candidates. Ambiguity, staleness, or insufficient scope stops or suspends preparation.
Authorization	Authorization	The post-grounding decision for the exact operation, using host-owned policy and trusted identity or scope. Approval may inform authorization but cannot prove an external effect.
Execution Identity	Protected execution	Operation, effect, execution, and attempt identities bind the protected run to the grounded operation. They provide continuity but do not prove exactly-once execution or external effect.
Attempt	Dispatch and acknowledgment	The dispatch boundary and provider observation. `ACKNOWLEDGED` belongs to Attempt; it means the provider received or accepted a request, not that the authoritative effect is `COMMITTED`.
Authoritative Effect	Independent verification; effect truth and projection	The authoritative business system owns external state. An independent verifier reads it and supplies evidence from which effect truth may be classified. Provider acknowledgment, telemetry, and local records do not replace that evidence.
Reconciliation	Reconciliation	Verifier/read-only resolution of knowledge about the original unresolved effect. It does not create another physical Attempt or authorize blind redispatch.
Permitted Claim	Effect truth and projection	The bounded projection and claim permission determine what may be asserted externally. The projection communicates supported effect truth without exposing private evidence or widening authority.

Trusted context supports grounding, authorization, and protected execution. The

provider attempts the change, while the verifier independently reads the system

that owns the fact. UNKNOWN is unresolved effect truth, never permission to

redispatch; a retry or compensation is a new proposal requiring fresh grounding and

authorization. Telemetry may support investigation but is not automatically effect

proof.

ClaimPermission is the structured Core/code artifact used to express permission.

Permitted Claim is the Semantic Integrity Chain stage describing the bounded

external assertion. They are related but not interchangeable. See the [Core

lifecycle concepts](/docs/core-lifecycle) and safe claims,

then continue with Grounding and authorization,

Execution and reconciliation,

Provider adapters, and

Independent verifiers.

End-to-end sequence

The following is the Runtime-oriented operational walkthrough for the semantic

crosswalk above.

The host accepts and validates the proposal.
The host supplies requester, tenant, subject, policy, and source context.
The host supplies authoritative candidates; Core resolves or requests clarification.
The host binds confirmation and authorization to the grounded operation.
Runtime/Core prepares an execution with operation, effect, execution, and attempt identities.
The host-owned provider adapter dispatches once.
A separate verifier reads the authoritative system.
PRESENT supports COMMITTED; ABSENT_FINAL supports DISPROVED; INDETERMINATE yields UNKNOWN.
The host projects only a permitted, bounded user-facing claim.

ACKNOWLEDGED means the provider observed or accepted the dispatch request. It is not COMMITTED. An UNKNOWN result is not permission to redispatch.

A live Runtime reconciliation handle is process-local and cannot itself be used after process loss. Separately, Runtime durable recovery supports verifier-only rehydration from a host-retained closed DurableRecoveryRecordV2 through accepted recovery authority and stable verifier registration. It performs authoritative read-back only, with source-record digest and CAS protections; it may yield COMMITTED, DISPROVED, or another UNKNOWN version-2 record and never grants execution or redispatch permission. Hosts own persistence, routing, authority controls, leases/fencing where required, scheduling, monitoring, and bounded delivery. This is not automatic or AnswerUp-hosted recovery, exactly-once execution, universal restart handling, or universal or production-grade durability.

Responsibility matrix

The following guidance keeps business authority, lifecycle classification, execution

orchestration, provider mutation, verification, and customer presentation separate.

Actor responsibilities

Actor	Owns or may supply	Must not claim or do
Agent, model, or framework	User or workflow intent, bounded proposal content, and proposed arguments	Cannot establish trusted identity, tenant scope, authorization, execution identity, or effect truth; cannot widen authority
Host application or backend	Authentication, trusted context, tenant or project scope, business policy, candidate lookup, provider and verifier credentials, customer-facing behavior, and operational decisions	Must not treat model output, provider acknowledgment, telemetry, or local state as effect truth; must not dispatch before grounding and authorization
Core package	Semantic lifecycle evaluation, exact grounding relationships, evaluation of the host-supplied authorization contract after grounding, execution identity binding, effect classification, and bounded claim permission	Does not own business policy, provider or verifier I/O, business searches, credentials, persistence, or hosted execution
Runtime	Process-local orchestration, execution sequencing, dispatch and verification coordination, projection, and durable verifier-only version-2-record rehydration through accepted recovery authority	Does not provide hosted durability, automatic recovery, or exactly-once execution; does not convert acknowledgment into effect truth or redispatch on `UNKNOWN`
Actions	Higher-level protected operations and exact-result, one-shot live reconciliation through verifier-only read-back	Does not make clones or serialized results authoritative, survive process loss, or redispatch a provider during reconciliation
Actions	Protected-action and provider/verifier contract façade, bounded action inputs, outcomes, and projection surfaces	Is not a provider, verifier, business authority, credential store, durable host, or independent source of effect truth
Provider	The attempted external mutation and bounded dispatch or acknowledgment observation within the host-owned integration	Cannot prove its own external effect merely by acknowledging dispatch; cannot change trusted scope or execution identity
Verifier	Independent read-only evidence from the authoritative business system: `PRESENT`, `ABSENT_FINAL`, or `INDETERMINATE` under the accepted verifier and finality contract	Must not mutate, dispatch, retry, guess, or self-authorize; must reject wrong-scope, stale, contradictory, or insufficiently final evidence
Authoritative business system	External business records and the state that determines whether the intended effect exists	Does not obtain truth from a provider acknowledgment or from AnswerUp’s local record
Operator or support function	Host-governed monitoring, investigation, escalation, retention, redaction, and recovery procedures	Cannot rewrite effect truth, manufacture `ClaimPermission`, reconstruct stale authority, or assert unsupported success
Customer, Product Maker, or enterprise	Tenant ownership, customer policy, business meaning, data governance, and the appropriate customer-facing system of record	Does not transfer tenant, policy, data, credential, or business-system authority to AnswerUp merely by using Core

Records and lifecycle relationship

Actor	Records/persistence responsibility	Applicable lifecycle relationship
Agent, model, or framework	Supplies proposal and bounded evidence inputs to the host; no authoritative persistence	Evidence, Proposal
Host application or backend	Owns durable lifecycle records, retention, access control, recovery, tenant isolation, and external response records	Evidence, Proposal, Grounding, Authorization, Execution Identity, Attempt, Reconciliation, Permitted Claim
Core package	Produces bounded semantic artifacts, identities, effect classification, and claim-permission decisions; the host persists them	Evidence, Proposal, Grounding, Authorization, Execution Identity, Attempt, Authoritative Effect, Reconciliation, Permitted Claim
Runtime	Owns process-local handles and lifecycle sequencing; durable recovery remains host-owned	Execution Identity, Attempt, Authoritative Effect, Reconciliation, Permitted Claim
Actions	Carries bounded protected-action, provider/verifier, outcome, and projection data; owns no authoritative or durable record	Protected action, Attempt observations, effect projection, and claim-permission surface
Provider	Returns provider-side dispatch and acknowledgment observations through the host	Attempt
Verifier	Returns bounded read observations and finality evidence without mutation	Authoritative Effect, Reconciliation
Authoritative business system	Owns external business state and authoritative effect truth	Authoritative Effect
Operator or support function	Retains privacy-safe case references, investigation records, and escalation history	Reconciliation, Permitted Claim
Customer, Product Maker, or enterprise	Owns customer records, policy records, tenant history, governance, and product-specific projections	All applicable stages within the customer architecture