@sequenceholdings/managed-functions 0.4.0 → 0.4.2

package/README.md

@@ -1,5 +1,75 @@
 # `@sequenceholdings/managed-functions`
 
+## Group-member directory lookup (internal rollout)
+
+Functions can resolve selected members of existing Atlas groups to active,
+canonical user identities. This is an opt-in read capability, not a staff
+registry, permission grant, arbitrary directory search, or authentication API.
+
+```yaml
+capabilities:
+  directory:
+    groups: ["<existing-group-id>"]
+```
+
+```ts
+import { createFunctionDirectoryClient } from '@sequenceholdings/managed-functions'
+
+const directory = createFunctionDirectoryClient({
+  baseUrl: process.env.ATLAS_ORIGIN!,
+  request: req,
+})
+const { members } = await directory.resolveMembers({
+  groupId,
+  subs: [selectedCanonicalSubject],
+})
+```
+
+Use `userIds` instead of `subs` to resolve row IDs selected from the existing
+group picker; never submit both. Each call accepts 1–50 selectors. Missing,
+disabled, tombstoned, wrong-tenant, or nonmember selections are omitted. Exact
+subject lookup does not accept an email alias. For a save, require the selected
+subject to appear exactly in the response; a failed request is not an empty
+successful lookup. Historical display labels may retain inactive identities,
+but cannot validate a new assignment.
+
+Atlas supplies a dedicated five-minute `x-sequence-directory-token` only for
+declared groups on direct human invocations. System runners and service accounts
+are not supported. Each read rechecks current function invocation access,
+active version, declared group scope, active caller, caller group visibility,
+and active target identities inside the function's tenant. No service identity
+widens the caller's directory visibility. The function still enforces its own
+application action permissions. Validation is point-in-time, not atomic with
+an application's later transaction.
+
+Directory and process-read clients share the SDK's invocation transport and
+`{ request, baseUrl, fetchImpl? }` options. Both accept Fetch `Headers` or Node
+request headers (case-insensitively), reject duplicate credentials, check expiry
+before each read, and validate responses. `FunctionDirectoryReadError` exposes
+`status` and `code`, like `FunctionProcessReadError`; failures are never an empty
+member list. Directory replies must contain only distinct requested identities.
+Sharing transport does not share authority: process reads retain service-account
+credentials, while directory reads retain their separate human-caller credential.
+
+The internal SDK bridge is `POST /api/managed-functions/directory/members`;
+ordinary Auth0 bearers, storage tokens and ORM tokens do not authenticate it.
+Results are not cached; successful reads emit an audit event. The client never
+follows redirects or forwards an unrelated credential. Allow the Atlas origin
+in the function's existing egress policy. Reviewed Atlas/CLI and SDK releases
+are required before consumers opt in (SDK 0.4.1+, CLI 0.5.2+, and Atlas
+advertising `directory_members`). Preflight rejects absent/disabled support
+and incompatible tooling before upload; older deployments do not supply the
+header. This addition does not activate or redeploy any consumer. The existing
+package root remains Preview/blocked on publication; the raw HTTP route is
+internal, not a new public API contract.
+
+Tenant deployments reuse `ATLAS_ARTIFACT_STUDIO_SIGNING_KEY`, already provided
+by the OpCo secrets catalog for Managed Functions. Delegation uses a separate
+HMAC domain, audience, environment, function version and invocation binding.
+There are no new secrets, migrations, groups or grants. Missing signing
+configuration fails closed, including local development.
+
+
 `@sequenceholdings/managed-functions` is the TypeScript SDK for Managed
 Functions. It provides caller-scoped ORM access, explicit service-account ORM
 access, and opt-in caching. The
@@ -11,9 +81,32 @@ generic invocation, isolation, secrets, egress, caching, and observability;
 deployed functions own business logic. Primitive code must not identify a
 function consumer or branch on a function ID.
 
+## Immutable function releases
+
+With CLI **0.5.5**, SDK **0.4.2**, and a platform deployment advertising the
+`immutable_release` capability, opt in before a new function's first deployment:
+
+```yaml
+function:
+  id: lending-capture-release-20261013
+  title: Lending capture release
+  immutable_release: true
+```
+
+The first successful activation records a permanent platform flag. That function
+identity cannot subsequently deploy, promote, roll back, change its runtime
+configuration, or redeploy for rotated secret versions. Removing the manifest
+field cannot undo the flag. Create a new function ID for the next release, and
+retain old identities while workflows still reference them. A mutable function
+that already activated cannot be converted into an immutable release.
+
+An exact retry of an already successful deployment returns its stored result
+without replacing the runtime. Failed initial deployments remain retryable until
+activation succeeds. Omission or `false` retains existing mutable behavior.
+
 ## ORM as the invoking user
 
-### Default SQL (planned SDK 0.4.0)
+### Default SQL (introduced in SDK 0.4.0)
 
 With the matching Atlas runtime, use the same caller-scoped executor without
 an operation manifest:
@@ -112,9 +205,38 @@ fragment or embedded credentials. Loopback HTTP is accepted for a local platform
 There is no automatic environment URL: the helper never trusts a request header
 or body to choose where it sends a delegated credential.
 
+### Gateway caller metadata
+
+The invoke gateway supplies `x-sequence-function-caller`, a base64url JSON object
+with `kind` (`human` or `service`), `sub`, `email`, `functionSlug`, `bodyHash`
+(SHA-256 of the dispatched JSON body), and `exp` (Unix milliseconds). Email is
+nullable. System runners and service accounts receive no human email; the person
+who initiated a workflow is not silently treated as its acting user.
+
+This metadata is gateway-owned and requires platform-only authenticated ingress
+(Cloud Run IAM or the authenticated local runtime). It is not a bearer token or
+signature. Do not accept it on a public handler, forward caller-supplied headers,
+or use the hash as authentication. Consumers must check function/body binding
+and expiry. Identity comes from the effective authenticated principal, including
+platform-authorized impersonation, rather than tool arguments. An external
+integration must still verify that this identity owns the vendor account it uses.
+
 ### Caller identity and trust boundary
 
-This helper supports direct human invocations through the platform gateway.
+`createFunctionCallerOrmExecutor` takes the same options and acts as the actual
+invoking human **or** platform service account. It requires the distinct
+gateway-delivered caller credential, explicitly signed as caller mode. Agents
+preserve their authenticated run account; a Lattice node with an explicit
+`run_as.service_account` can use that account's namespace floor, capabilities
+and row policies. A system/M2M run has no caller credential, and a recorded run
+starter is never used as the actor. Missing or denied caller access never falls
+back to the function's attached account. This helper requires a matching
+platform runtime; older deployments fail closed with `MISSING_CALLER_CONTEXT`.
+Caller service accounts are checked for current existence and disabled state
+on every ORM operation. The delegated grant has its own invocation expiry; it
+does not promise to track revocation of the API credential that started it.
+
+The legacy `createFunctionOrmExecutor` helper supports direct human invocations through the platform gateway.
 Scheduled/system-runner and service-account invocations fail closed. They do not
 silently become an attached service account or a recorded human initiator.
 
@@ -202,6 +324,18 @@ const page = await processes.listRunsPage({
 })
 ```
 
+With SDK 0.4.2 and both exact process and agent read declarations,
+`processes.getCompletedAgentReference({ process, runId, nodeId })` recovers only
+`{ stepId, attempt, agentId, agentRunId, threadId }` for a unique completed
+top-level agent step in a terminal process run. The parent may have failed,
+timed out or been cancelled after that agent finished. Both live credentials
+must belong to the same receiving invocation. Current Process, Run, Agent, Job
+and Thread visibility, actual source ownership, frozen bundle pins and immutable
+private execution source remain enforced. Active or ambiguous attempts are
+refused. The reference grants no history access and does not assert successful
+business completion; the application still checks its current generation,
+release and lease before using it.
+
 `getRun` returns only `id`, `processId`, `status`, `entityType`, `entityId`,
 `startedAt` and `completedAt`. Dates are ISO strings; entity fields and
 `completedAt` may be null. Runtime error text, metadata, state, output and steps
@@ -224,6 +358,171 @@ empty activity list. Reads do not atomically reserve work: applications must
 still coordinate concurrent starts through a durable claim or idempotency
 mechanism.
 
+## Resolve exact directory principals
+
+This addition targets SDK **0.4.2**, CLI **0.5.5**, and a deployment advertising
+`directory_resolve`. Confirm public package availability before installing the
+new versions. Declare exact registered tenant scopes and attach an account:
+
+```yaml
+service_account: app-directory-reader
+capabilities:
+  directory:
+    resolve: [example_tenant]
+```
+
+```ts
+import { createFunctionServiceDirectoryClient } from '@sequenceholdings/managed-functions'
+
+const directory = createFunctionServiceDirectoryClient({ request, baseUrl: platformOrigin })
+const result = await directory.resolve({
+  tenant: 'example_tenant',
+  lookups: [{ type: 'email', value: 'reviewer@example.com' }],
+})
+```
+
+Use at most 50 distinct exact email or subject lookups per call and at most 16
+tenant scopes in the declaration. The account needs the separate current
+Directory Reader grant for the requested tenant; directory administration is
+not a substitute. Each call rechecks the current function version, declaration,
+live invocation and account. The client uses only its invocation-scoped
+directory credential and refuses redirects.
+
+`resolved` entries contain the original lookup plus `sub`, `email` and `name`;
+`unresolved` contains the remaining lookups. Inactive, deleted, unlinked,
+ambiguous and machine identities are unresolved. Unknown or inaccessible
+tenants return the same authorization error. This is not a searchable user
+listing. `DirectoryPrincipalResolveError` exposes `status` and `code`; a denied,
+unavailable or malformed response must not become an empty resolution result.
+
+## Abrigo reads as the actual caller
+
+The upcoming SDK **0.4.2** and CLI **0.5.5** support a deployment-advertised
+`abrigo_read` capability. Declare only the needed finite read operations in
+`capabilities.abrigo.read` and attach a `service_account` for the receiving
+function. `createFunctionCallerAbrigoClient({ request, baseUrl: platformOrigin })`
+provides `read(query)` for `workflow`, `entity`, `entityGroupSummary`,
+`loanRoles`, `relatedLoanRoles`, `workflowLoanMappings`, `workflowDocuments`
+and `customerDocuments`, plus the narrow `reviewWorkflow`,
+`reviewWorkflowDocuments` and `reviewWorkflowCustomerDocuments`. A declaration
+contains 1 to 11 distinct operations.
+
+All reads use the invocation's actual human caller, live receiver lease and
+current function Invoker grant. The original eight operations also require that
+person's current Abrigo integration access. The three review operations use the
+native document-read gate, which also admits Underwriting Approvers.
+Service-account and system callers are refused; the attached function account
+never supplies replacement authority.
+The client has no arbitrary path, write, actor or credential parameter.
+
+Review queries take only a `workflowId`, plus pagination for documents.
+`reviewWorkflow` returns exactly `{ id, customerId }`. The customer-document
+operation derives the actual workflow customer at the broker; callers cannot
+select a `customerId`. Each response retains authoritative `workflowId` and
+`customerId`, including empty pages. Application code must compare each page's
+customer with the initial workflow customer to detect changes while paging.
+Both document review operations require an object envelope with an `items`
+array bounded by the requested `perPage`; vendor pagination metadata is retained.
+
+Collection queries require an explicit `page` from 1 to 100 and `perPage` from
+1 to 500. Responses are bounded to 1 MiB and refuse malformed JSON, nonfinite
+numbers and unsafe integers, so vendor IDs are never silently rounded.
+Oversized or unavailable reads fail explicitly. Application code still
+validates the response, pagination completeness and business membership.
+`FunctionAbrigoReadError` retains a safe status/code without exposing vendor
+error bodies.
+
+## Verified invocation identity
+
+With SDK 0.4.2, CLI 0.5.5 and a host advertising `invocation_identity`, a
+function with an attached `service_account` can opt into its verified receiver
+and actual caller:
+
+```yaml
+capabilities:
+  invocation:
+    identity: true
+```
+
+```ts
+import { createFunctionInvocationClient } from '@sequenceholdings/managed-functions'
+
+const invocation = createFunctionInvocationClient({ request, baseUrl: platformOrigin })
+const { receiver, caller } = await invocation.getInvocationContext()
+```
+
+The receiver identifies this function, version, invocation, organization and
+attached service account. The caller is the authenticated human, service
+account or system principal that invoked it; the attached account and a
+workflow's recorded starter are not substitutes for that caller. The request
+has no caller-supplied identity selector. Each read verifies the signed
+credential, current invocation, attached account and actual caller's current
+function Invoker access; expired or revoked context fails closed. Identity
+metadata grants no ORM access or domain authority: the handler must check its
+own expected release and business policy, and use a
+separately declared caller or service executor for data access.
+
+## Trusted Lattice execution and human actions
+
+Functions invoked by a first-class Lattice node can opt into invocation-scoped
+context reads. Attach a `service_account` and declare:
+
+```yaml
+capabilities:
+  lattice:
+    context: true
+```
+
+These reads also require the actual caller's current process Viewer and run
+Viewer access. Process Invoker already inherits those Viewer permissions;
+the attached account does not replace the actual caller's authorization.
+
+```ts
+import { createFunctionLatticeClient } from '@sequenceholdings/managed-functions'
+
+const lattice = createFunctionLatticeClient({ request, baseUrl: 'https://your-environment.example.com' })
+const execution = await lattice.getExecutionContext()
+const review = await lattice.getHumanCompletion({ nodeId: 'review' })
+const votes = await lattice.getHumanCompletions({ nodeId: 'vote', ancestorNodeId: 'review' })
+const committee = await lattice.getParallelSnapshot({ nodeId: 'committee', ancestorNodeId: 'review' })
+```
+
+`execution.input` is the persisted node mapper output. `execution.ctxSnapshot`
+includes platform-owned run/entity identity and only data explicitly mapped as
+`input.context`; omitted upstream, state and metadata remain hidden. A reviewed
+node can explicitly map `{ context: ctx, input: domainInput }` when it needs the
+full context. Direct function invocations have no Lattice credential.
+
+`execution.receiver.invoker` identifies the authenticated caller, including its
+kind and authentication method. `attachedServiceAccountSub` identifies the
+function's separate attached account. Neither is inferred from the run starter;
+the SDK checks both against the invocation credential.
+
+`execution.run.startProvenance` describes the verified authorization that
+admitted this pinned run: its actor, start mode and basis, authorization time,
+and scheduler admission when applicable. The platform verifies the persisted
+stamp against the actual run pins and recorded starter; authored trigger reasons
+or context metadata are never substitutes. Older runs may omit this field or
+return `null`. A start stamp records the original admission decision, rather
+than granting current permissions or identifying a later human action.
+
+Human reads verify a platform-signed receipt against the actual completed step,
+current receiving invocation, frozen graph and causal subprocess lineage. The
+caller must still check the expected action, task, approval generation and
+business authority. Run starters, `advanced_by`, email and `assertedBy` alone are
+not approval evidence. Forked/copied history, timeouts, stale attempts and revoked
+invocations fail closed; legacy completions without receipts require a fresh
+human action. `getHumanCompletions` returns at most 64 selected causal receipts.
+
+For parallel nodes declared with `captureProvenance: true`,
+`getParallelSnapshot` returns the completed join's canonical proof and frozen
+`observedAt`, its causal ancestor receipt, and at most 64 actual branches. Branch
+IDs, indexes, items, step attempts, statuses and human receipt IDs are preserved.
+An early join may include pending branches; later cancellation does not rewrite
+that observation. The SDK preserves the server's proof and timestamp, while the
+platform verifies the signed source rows. The handler still decides whether the
+observed votes satisfy its business policy.
+
 ## Opt-in cache
 
 Opt-in caching inside a Managed Function. When the manifest declares a `cache` block, the platform passes a process-reused `context` as the HTTP handler's third argument. Existing two-argument handlers keep working.
@@ -271,6 +570,72 @@ Explicit CRUD throws `CacheError` with `DISABLED`, `UNAVAILABLE`, `UNKNOWN_OUTCO
 
 Authors own authorization, read/write choices, and invalidation. A concurrent loader can repopulate a deleted key with old data; use authoritative versioned keys or bypass the cache when freshness is required. Every activation gets a fresh key namespace; old entries expire naturally.
 
+## Deliver app-owned monitoring observations
+
+Monitoring delivery requires SDK **0.4.2**, CLI **0.5.5**, and a deployment
+advertising `monitoring_deliveries`. Declare the exact producer namespaces:
+
+```yaml
+service_account: app-effects
+capabilities:
+  monitoring:
+    producers: [inbox, documents]
+```
+
+Declarations grant no monitoring authority. The attached account needs the
+producer namespace's runtime floor and pinned `emit_monitoring` capability.
+Continuous Improvement must also register that exact namespace and authorize
+publishing or catalog reads. Registrations default to inactive with both
+operations disabled. Only a human with current Monitoring Admin authority can
+review and change this consent; owning or creating a namespace cannot approve
+its use of CI. Deployment never creates registrations or grants that consent.
+The namespace and function must belong to the same registered tenant. Every
+call rechecks the current manifest, active version, live invocation reservation,
+account availability, and namespace claims. Bearer, ORM, Storage, and process
+credentials are never accepted as monitoring credentials.
+
+Invocation credentials bind the registration ID and epoch. Publish, receipt
+lookup, and catalog reads lock and recheck current consent on their transaction
+connection. Revocation blocks old credentials, including after re-enabling a
+producer. A new invocation can recover an older immutable receipt after renewed
+consent; the receipt retains its original accepted epoch and business payload hash.
+
+```ts
+import {
+  createFunctionServiceMonitoringClient,
+  monitoringPayloadHash,
+} from '@sequenceholdings/managed-functions'
+
+const monitoring = createFunctionServiceMonitoringClient({ request, baseUrl: platformOrigin })
+const payloadHash = monitoringPayloadHash({ events, observation })
+const receipt = await monitoring.publish({ producer: 'inbox', businessKey, payloadHash, events, observation })
+// After an ambiguous response, look up the immutable key before retrying.
+const recovered = await monitoring.get({ producer: 'inbox', businessKey })
+```
+
+The app freezes accepted inputs, timestamps, event keys, and optional interpreted
+CI annotations before computing the hash. Object keys are sorted, array order
+is retained, and contract defaults are applied. `idempotencyKey` on each input
+event identifies one claim within the delivery; Atlas derives a storage key
+from the trusted tenant, namespace, business key, and that claim key. It cannot
+overwrite another producer's or a legacy native event.
+
+An identical retry returns the same receipt; changed content under the same
+business key returns **409**. Up to 100 events and 512 KiB per delivery are
+accepted. A legitimate zero-event result still receives a hash-bound receipt.
+`get` throws `FunctionMonitoringError` with status **404** if the key is absent.
+Both publishing and lookup require producer authorization.
+
+`getBucketCatalog({ producer })` reads only the complete active taxonomy
+metadata under the separate namespace `read_monitoring_catalog` capability.
+Freeze that catalog with the analysis inputs. More than 2000 buckets or 512 KiB
+returns an explicit size error; the client never treats a partial catalog as complete.
+
+`confirmed` means the submitted CI events and supplied product observations
+committed atomically. It does not mean later triage, clustering, or agent analysis
+completed. The source app performs analysis and constructs neutral events;
+intake never reads native Inbox data to interpret a completion or correction.
+
 ## Local development
 
 Run `seq-studio functions dev --dir . --port 8080` after installing dependencies. Enabled caching without a Valkey connection uses bounded process-local TTL/LRU storage (16 MiB encoded payloads, 10,000 entries); it is reset on restart and not shared across processes. The harness compiles TypeScript with the project's installed compiler. A deployed enabled cache without connection configuration fails startup; it never falls back silently.
@@ -285,6 +650,83 @@ Cloud Run emits aggregate `managed_function.cache` logs every 30 seconds of acti
 
 Functions without a `cache` manifest block retain their existing two-argument handler. An explicit `cache: { enabled: false }` supplies a disabled `context.cache`, allowing `getOrCompute` to run its loader without caching.
 
+## Completed agent responses
+
+With SDK 0.4.2, CLI 0.5.5 and a deployment advertising `agents_read`, declare
+exact agent IDs in `capabilities.agents.read` and attach a `service_account`.
+Inside each invocation, call
+`createFunctionServiceAgentsClient({ request, baseUrl: platformOrigin }).getCompletedRun({ agent, runId })`.
+The account needs current agent Viewer access. The declaration grants no access
+to another caller's conversations: both the run and private thread must belong
+to the attached account, or be a verified completed upstream agent step in the
+same immutable Lattice execution context.
+
+The response contains persisted completed output, assistant text, citation
+resources and a neutral conversation projection for counts and tool-state metrics.
+It excludes reasoning, reasoning-derived compaction, arbitrary tool results and inputs, and private
+thread configuration. Reused conversations and experimental ORM history are
+denied. Verified same-step structured-output re-asks remain readable; messages
+changed after completion are refused. Results
+over 1,000 messages or 8 MiB fail explicitly; a partial response never substitutes
+for a full generated answer. No thread listing or arbitrary thread-ID read exists.
+
+For protected application source records, declare the same exact IDs in
+`capabilities.agents.evidence` on a deployment advertising `agents_evidence_verify`.
+`createFunctionServiceAgentsClient(...).captureCompletedRun({ agent, runId })`
+returns `{ response, responseHash, sourceReceipt }` for a completed source owned
+by the attached account. This neutral capture also requires the live read
+credential; it cannot capture another user's source through upstream lineage.
+The signed receipt identifies the actual service account and the invocation that
+captured evidence, separately from the original agent-run creator. Human captures
+identify the actual signed-in user instead. Neither kind grants read access.
+
+`createFunctionAgentEvidenceClient({ request, baseUrl: platformOrigin }).verifySourceEvidence({ agent, runId, response, responseHash, sourceReceipt })`
+verifies supplied historical bytes without fetching conversation history. Its
+separate invocation credential rechecks the current function version, attached
+account, exact evidence scopes, positive invocation lease and Agent Viewer floor.
+The result separates the historical source from the current receiving invocation.
+The application must also enforce its protected release, source and receiver
+associations. Capture responses over 512 KiB and verification requests over
+768 KiB fail before writing; neither operation truncates evidence.
+
+For an explicitly captured user sidebar, call the same evidence client's
+`verifyConversationEvidence({ agent, threadId, response, responseHash, sourceReceipt })`.
+This separate source projection binds a durable settled conversation revision
+and cutoff rather than inventing an agent run. It verifies only previously
+authorized captured bytes; the function gains no arbitrary thread-read access.
+
+## Completed private workflow sources
+
+The upcoming SDK **0.4.2** and CLI **0.5.5** add separate workflow capture and
+evidence clients. Confirm publication and the deployment's `workflows_read`
+and `workflows_evidence_verify` features before depending on them. Declare
+exact workflow IDs in `capabilities.workflows.read` and
+`capabilities.workflows.evidence`, and attach an approved `service_account`.
+
+`createFunctionServiceWorkflowsClient({ request, baseUrl: platformOrigin })`
+provides `captureCompletedRun({ workflow, runId })`. Capture requires both
+declarations, the source-owning account's current Workflow Invoker and root
+and child Job Viewer access, and the exact verified completed upstream
+workflow execution. It returns `{ response, responseHash, sourceReceipt }`
+for the root's persisted merged JSON. The signed evidence retains failed or
+skipped branch outcomes; capture does not imply every branch succeeded. It
+does not read conversations or reuse an Agent response type.
+
+`createFunctionWorkflowEvidenceClient({ request, baseUrl: platformOrigin })`
+provides `verifySourceEvidence({ workflow, runId, response, responseHash,
+sourceReceipt })`. Verification uses its separate evidence declaration and
+current invocation credential. It verifies supplied historical bytes without
+fetching output. The signed historical source, any genuine job-admission
+reference, and the current receiver remain separate: the application must
+bind them to its protected current task and intent. Historical evidence grants
+no current source-read authority or application write authority.
+
+Capture is bounded to 512 KiB, verification requests to 768 KiB, and opaque
+source receipts to 16 KiB. Incomplete or changed source records are refused;
+oversized results fail explicitly without truncation. Clients preserve typed
+`FunctionWorkflowReadError` status/code failures rather than treating them as
+empty results.
+
 ## Runtime tracing
 
 Newly deployed function entrypoints install request-scoped tracing automatically,

package/dist/abrigo-contract.d.ts

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+export declare const FUNCTION_ABRIGO_READ_TOKEN_HEADER = "x-sequence-abrigo-read-token";
+export declare const FUNCTION_ABRIGO_READ_PATH = "/api/managed-functions/abrigo/read";
+export declare const FUNCTION_ABRIGO_READ_AUDIENCE = "atlas-managed-function-abrigo-read";
+export declare const ABRIGO_READ_MAX_RESPONSE_BYTES: number;
+export declare const ABRIGO_READ_TIMEOUT_MS = 30000;
+export declare const abrigoReadOperationSchema: z.ZodEnum<{
+    workflow: "workflow";
+    entity: "entity";
+    entityGroupSummary: "entityGroupSummary";
+    loanRoles: "loanRoles";
+    relatedLoanRoles: "relatedLoanRoles";
+    workflowLoanMappings: "workflowLoanMappings";
+    workflowDocuments: "workflowDocuments";
+    customerDocuments: "customerDocuments";
+    reviewWorkflow: "reviewWorkflow";
+    reviewWorkflowDocuments: "reviewWorkflowDocuments";
+    reviewWorkflowCustomerDocuments: "reviewWorkflowCustomerDocuments";
+}>;
+export type FunctionAbrigoReadOperation = z.infer<typeof abrigoReadOperationSchema>;
+export type AbrigoReadOperation = FunctionAbrigoReadOperation;
+export declare const functionAbrigoReadRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    operation: z.ZodLiteral<"workflow">;
+    workflowId: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"entity">;
+    entityId: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"entityGroupSummary">;
+    entityId: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"loanRoles">;
+    proposedLoanId: z.ZodNumber;
+    page: z.ZodNumber;
+    perPage: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"relatedLoanRoles">;
+    proposedLoanId: z.ZodNumber;
+    page: z.ZodNumber;
+    perPage: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"workflowLoanMappings">;
+    workflowId: z.ZodNumber;
+    page: z.ZodNumber;
+    perPage: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"workflowDocuments">;
+    workflowId: z.ZodNumber;
+    page: z.ZodNumber;
+    perPage: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"customerDocuments">;
+    customerId: z.ZodNumber;
+    page: z.ZodNumber;
+    perPage: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"reviewWorkflow">;
+    workflowId: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"reviewWorkflowDocuments">;
+    workflowId: z.ZodNumber;
+    page: z.ZodNumber;
+    perPage: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"reviewWorkflowCustomerDocuments">;
+    workflowId: z.ZodNumber;
+    page: z.ZodNumber;
+    perPage: z.ZodNumber;
+}, z.core.$strict>], "operation">;
+export type FunctionAbrigoReadRequest = z.infer<typeof functionAbrigoReadRequestSchema>;
+export declare const functionAbrigoReadScopesSchema: z.ZodObject<{
+    read: z.ZodArray<z.ZodEnum<{
+        workflow: "workflow";
+        entity: "entity";
+        entityGroupSummary: "entityGroupSummary";
+        loanRoles: "loanRoles";
+        relatedLoanRoles: "relatedLoanRoles";
+        workflowLoanMappings: "workflowLoanMappings";
+        workflowDocuments: "workflowDocuments";
+        customerDocuments: "customerDocuments";
+        reviewWorkflow: "reviewWorkflow";
+        reviewWorkflowDocuments: "reviewWorkflowDocuments";
+        reviewWorkflowCustomerDocuments: "reviewWorkflowCustomerDocuments";
+    }>>;
+}, z.core.$strict>;
+export declare function readFunctionAbrigoReadScopes(manifest: unknown): FunctionAbrigoReadOperation[];
+export declare class FunctionAbrigoReadError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly name = "FunctionAbrigoReadError";
+    constructor(status: number, code: string, message: string);
+}

package/dist/abrigo-contract.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FunctionAbrigoReadError = exports.functionAbrigoReadScopesSchema = exports.functionAbrigoReadRequestSchema = exports.abrigoReadOperationSchema = exports.ABRIGO_READ_TIMEOUT_MS = exports.ABRIGO_READ_MAX_RESPONSE_BYTES = exports.FUNCTION_ABRIGO_READ_AUDIENCE = exports.FUNCTION_ABRIGO_READ_PATH = exports.FUNCTION_ABRIGO_READ_TOKEN_HEADER = void 0;
+exports.readFunctionAbrigoReadScopes = readFunctionAbrigoReadScopes;
+const zod_1 = require("zod");
+exports.FUNCTION_ABRIGO_READ_TOKEN_HEADER = 'x-sequence-abrigo-read-token';
+exports.FUNCTION_ABRIGO_READ_PATH = '/api/managed-functions/abrigo/read';
+exports.FUNCTION_ABRIGO_READ_AUDIENCE = 'atlas-managed-function-abrigo-read';
+exports.ABRIGO_READ_MAX_RESPONSE_BYTES = 1024 * 1024;
+exports.ABRIGO_READ_TIMEOUT_MS = 30_000;
+exports.abrigoReadOperationSchema = zod_1.z.enum([
+    'workflow', 'entity', 'entityGroupSummary', 'loanRoles', 'relatedLoanRoles',
+    'workflowLoanMappings', 'workflowDocuments', 'customerDocuments',
+    'reviewWorkflow', 'reviewWorkflowDocuments', 'reviewWorkflowCustomerDocuments',
+]);
+const id = zod_1.z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+const page = zod_1.z.number().int().min(1).max(100);
+const perPage = zod_1.z.number().int().min(1).max(500);
+exports.functionAbrigoReadRequestSchema = zod_1.z.discriminatedUnion('operation', [
+    zod_1.z.strictObject({ operation: zod_1.z.literal('workflow'), workflowId: id }),
+    zod_1.z.strictObject({ operation: zod_1.z.literal('entity'), entityId: id }),
+    zod_1.z.strictObject({ operation: zod_1.z.literal('entityGroupSummary'), entityId: id }),
+    zod_1.z.strictObject({ operation: zod_1.z.literal('loanRoles'), proposedLoanId: id, page, perPage }),
+    zod_1.z.strictObject({ operation: zod_1.z.literal('relatedLoanRoles'), proposedLoanId: id, page, perPage }),
+    zod_1.z.strictObject({ operation: zod_1.z.literal('workflowLoanMappings'), workflowId: id, page, perPage }),
+    zod_1.z.strictObject({ operation: zod_1.z.literal('workflowDocuments'), workflowId: id, page, perPage }),
+    zod_1.z.strictObject({ operation: zod_1.z.literal('customerDocuments'), customerId: id, page, perPage }),
+    zod_1.z.strictObject({ operation: zod_1.z.literal('reviewWorkflow'), workflowId: id }),
+    zod_1.z.strictObject({ operation: zod_1.z.literal('reviewWorkflowDocuments'), workflowId: id, page, perPage }),
+    zod_1.z.strictObject({ operation: zod_1.z.literal('reviewWorkflowCustomerDocuments'), workflowId: id, page, perPage }),
+]);
+exports.functionAbrigoReadScopesSchema = zod_1.z.strictObject({
+    read: zod_1.z.array(exports.abrigoReadOperationSchema).min(1).max(11)
+        .refine((operations) => new Set(operations).size === operations.length, 'Abrigo read operations must be distinct'),
+});
+function readFunctionAbrigoReadScopes(manifest) {
+    if (typeof manifest !== 'object' || manifest === null)
+        return [];
+    const capabilities = Reflect.get(manifest, 'capabilities');
+    if (typeof capabilities !== 'object' || capabilities === null)
+        return [];
+    const abrigo = Reflect.get(capabilities, 'abrigo');
+    return abrigo === undefined ? [] : exports.functionAbrigoReadScopesSchema.parse(abrigo).read;
+}
+class FunctionAbrigoReadError extends Error {
+    status;
+    code;
+    name = 'FunctionAbrigoReadError';
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+exports.FunctionAbrigoReadError = FunctionAbrigoReadError;

package/dist/abrigo-response.d.ts

@@ -0,0 +1,6 @@
+import type { JsonValue } from './cache';
+import { type FunctionAbrigoReadRequest } from './abrigo-contract';
+export declare function validateAbrigoReviewResponse({ query, body }: {
+    query: FunctionAbrigoReadRequest;
+    body: JsonValue;
+}): void;