Operator

Manually match an unmatched evidence to an obligation

Manual match: settle the operator-pinned obligation and unwind the suspense park this evidence created (≤ 2 Hydra txs, each leg idempotent). The evidences row flips to MANUALLY_MATCHED; a second call 409s.

Parâmetros

Corpo da requisição

EvidenceResolveRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Retry a failed evidence ingest

Re-run a stored `status=ERROR` evidence row through the ingest pipeline once its cause is fixed (zero recorded effects only). A still-unfixed cause surfaces the same 4xx the original ingest returned.

Parâmetros

Corpo da requisição

EvidenceRetryRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Re-drive a failed outbound dispatch

Re-queue a FAILED dispatch (or the enqueue-failure signature). EXCEPTION rows return to FINAL(null), `dispatch_status` becomes RETRY_REQUESTED, and a fresh `outbound_dispatch` job is enqueued for tx-worker (RFC-022 §4.2).

Parâmetros

Corpo da requisição

ObligationRedispatchRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Operator resolve of a stuck obligation

Clear a PENDING/EXCEPTION obligation with an operator-attested outcome + proof (D1). Exactly one Hydra tx when the obligation UTxO is live (the value is disposed and the new output resolves FINAL on confirm — `hydra_tx_id` non-null); zero when spent/absent (metadata-only resolve). Accepts `obl_*` and legacy `txhash_N` ids.

Parâmetros

Corpo da requisição

ObligationResolveRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

List a tenant's compile jobs

This tenant's compile jobs, newest first. Source is never echoed back.

Parâmetros

Respostas

Submit a product bundle to the Foundry

Compile and gate one tenant-authored validator.

**202, not 201** — the job is accepted, not finished. Poll the companion `GET` for its verdict.

A submission that fails a static gate (the source admission scan, the manifest through `load_manifest`, the namespace check) comes back **already REFUSED** and is never queued: the compile slot is the expensive thing, and source that cannot pass a lexer will not pass a compiler.

⚠️ Compiling is not certifying and certainly not binding. A green report is evidence; conformance execution, the adversarial battery and a countersigned Certified Product Artifact are what make a product real, and nothing here writes to the bindable-template allowlist.

Parâmetros

Corpo da requisição

FoundryCompileRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Get one compile job and its gate report

One compile job, at whatever stage it has reached.

The gate report lists **every** gate that ran, passes included, plus a `deferred` block naming what this stage deliberately did not prove. A report that showed only failures could not answer "was this checked?", which is the question a countersigner asks.

⛔ A foreign tenant's `compile_id` and one that never existed are the same DynamoDB miss — the tenant is a partition-key segment, so 404-before-403 holds in its strongest form.

Parâmetros

Respostas

Read a submission's source (the P6 countersigner's read)

The tenant's Haskell, verbatim, for the human who has to sign off on it.

⛔ **This route exists because §4.3's countersignature is not a rubber stamp.** P6 requires a platform engineer to countersign *the report and the source*, and LaaS-88 D2 keeps the source out of the published evidence set — SSE-KMS, platform-only, referenced from the certification by hash. So there has to be exactly one way to read it, and this is it: operator-scoped, per compile, logged with the client that asked.

⚠️ **The honest cost of D2, stated where a reader meets it:** an outside auditor can verify every hash and both signatures and *cannot* check that the certified script came from the claimed source. Publishing the source would close that gap and would also publish a tenant's IP to everyone holding the evidence bucket. That trade was made deliberately.

Answers `text/plain` — the bytes as submitted, whose sha256 is the `source_hash` in the gate report.

Parâmetros

Respostas

Read a tenant's bundle-signing key enrollment

The active enrollment and the fingerprints it superseded, or 404.

Parâmetros

Respostas

Enroll a tenant's bundle-signing public key

Record the public key whose signature proves who authored a Product Bundle.

**Why this is an operator act and not self-service.** A tenant self-enrolling would make the recorded authority only as strong as the API credential that enrolled it — and outliving that credential is the whole reason a detached signature exists. The row records the enrolling client, so *who vouched that this key is the tenant's* has an answer.

Idempotent by fingerprint: the same key answers **200** with `enrolled: false`. A *different* key is refused **409** unless `replace: true`, and a rotation files the incumbent as superseded rather than overwriting it — a certification signed under the old key must keep verifying, so its PEM stays published under its own fingerprint.

Public key only. There is no field a private key could be pasted into and no code path that would know what to do with one.

Parâmetros

Corpo da requisição

ProductKeyEnrollRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

List a tenant's product bindings

This tenant's bindings, current version each, newest change first.

SUSPENDED and RETIRED products are listed. Lifecycle gates writing, never observation.

Parâmetros

Respostas

Get a tenant product binding

One binding: its current version, every version recorded, and its history.

⛔ A foreign tenant's `product_id` and one that never existed are the same DynamoDB miss — the tenant is a partition-key segment, so 404-before-403 holds in its strongest form: status, body, headers and the time taken to answer cannot differ.

Parâmetros

Respostas

Move a product binding through its lifecycle

DRAFT → CERTIFIED → LIVE → SUSPENDED → RETIRED, on the shipped table.

**LIVE** requires `attestation.signed_by` — the platform countersignature of founder decision P6. Pre-Foundry that is a recorded operator sign-off written into the row's `certification` block; laas-86 replaces it with the certified artifact's own signature, in the same field.

**SUSPENDED** is unilateral and immediate: the next create or advance answers 409 `PRODUCT_NOT_ACCEPTING_WRITES` while a close still serves, because the adapter re-reads the binding on every write and exempts the close role. Suspending must stop new instances, never strand the ones an operator suspended it to look at.

**RETIRED** is terminal — there is no un-retire and no unbind verb at all. History stays resolvable: an obligation whose product no longer resolves is an audit hole.

Parâmetros

Corpo da requisição

TenantProductLifecycleRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Bind a certified product artifact to one tenant

Bind one certified artifact to exactly one tenant.

The registry/bindings split (Product Plane §4.4): the artifact is content-addressed and published here, and the **row** is what activates it. Certification without binding deploys nothing.

For a parametric template this carries the whole job: resolve this tenant's binding params, apply them, derive the applied script hash and address the result produces, publish the applied bytes, and write the row with `applied.{template_hash, script_key, params, param_values}`. Two tenants binding one template get two addresses, and neither can be spent under the other's terms.

Idempotent on artifact identity: a repeat with a byte-identical manifest and the same baked-in params answers **200** with `bound: false` and appends no version. A changed manifest hashes differently and supersedes.

Parâmetros

Corpo da requisição

TenantProductBindRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Read a product's certification envelope

The signed certification, its countersignature if it has one, and staleness.

⭐ **Stale is reported, never enforced.** A battery upgrade does not invalidate a LIVE product: an inventory-hash bump would otherwise be an estate-wide outage triggered by adding an attack class, and the products it would take down are exactly the ones that passed the previous inventory honestly. The certification records `battery_version` and `inventory_hash`; this read compares them against what the estate ships now and says so. Re-certification is a deliberate act.

Everything needed to verify the artifact offline is in the response, and the published public keys live beside it in the store — `keys/product-platform-*.pub.pem` and `keys/product-countersigner-*.pub.pem`. Check it with `scripts/verify-product-certification.py`, which needs no platform access at all.

Parâmetros

Respostas

Certify a product binding against its evidence

Assemble the **Certified Product Artifact**, sign it, and record CERTIFIED.

Staples LaaS-83's gate report, LaaS-84's conformance transcript and LaaS-85's battery report card **by reference** into one content-addressed document, captures this product's golden vectors from its own IR schemas, records which relaxation policy authorised the path, signs the body with the platform certification key and publishes the envelope to the WORM certification store.

⛔ **It verifies evidence; it does not produce evidence.** Every named document is fetched, re-hashed against the hash the request gives, and checked for an `accepted` verdict and a matching subject. A route that produced its own evidence and then judged it would be a route that certifies itself.

⛔ **Nothing is published if the evidence does not support a certification.** A refused certification is not an artifact, and the store's objects cannot be deleted.

Also the re-certification path: run against a CERTIFIED or LIVE binding it replaces the certification block and leaves the state alone, because `CERTIFIED → CERTIFIED` is not an edge in the transition table and inventing one would make the table stop describing the machine.

Parâmetros

Corpo da requisição

TenantProductCertifyRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Plan a drain: how each open instance would be closed

Per open instance, the route that closes it — or the reason there is none.

Migration between versions is **close-and-reopen** (Product Plane §4.2 step 5): hash is address, so a new version is a new address by construction and no transaction moves value between them. This plans the closing half.

The routes come from the manifest's own close actions, walked by the same planner conformance uses — a per-product drain command would be the platform re-authoring what the tenant declared. An instance in a reachable non-terminal state with **no path out** is reported as `no_route` by name: its value is stranded, that is a manifest defect rather than an operational one, and no drain will move it.

Read-only. `POST` to the same path executes, and it needs an explicit id list.

Parâmetros

Respostas

Drain a product: close the named instances

Close the instances named in `instance_ids`, through the shipped close path.

⛔ Needs `consent: true` and an explicit id list. There is no close-everything shape, because the operator reaching for a drain is usually reaching for it under time pressure and a plan they did not read is not consent.

⚠️ **Best-effort per instance, and it does not stop on the first failure.** Every close is independent, so there is nothing a rollback could mean — and a drain that aborted half-way would leave an operator with no record of which closes landed. Each instance gets its own outcome in `results`.

Parâmetros

Corpo da requisição

TenantProductDrainRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

List a tenant's processor accounts

Every processor account this tenant holds.

Never carries credential material — that crosses out once, on the call that opened the account, and is not recoverable from here or from the processor.

Parâmetros

Respostas

Open a tenant's account at a processor

Open one account for this tenant at a processor, and record it.

⚠️ **The response carries the account's credential exactly once, and the platform never stores it.** A processor that mints one at creation cannot show it again — capture it from this response and provision it at the `credential.secret_ref` path, which is where the driver resolves it from. Until that is done the binding answers `credential_status: PENDING_PROVISION` and any dispatch through it fails closed with a config error rather than moving money with no credentials.

Idempotent **by the recorded account**, not by an `Idempotency-Key`: if this tenant already holds an account at this provider the processor is never called, because opening an account is *not* idempotent at the far end — a retry opens a second real account. A repeat returns the existing binding with `provisioned: false` and no credential.

A **different** account already bound for the same tenant and provider is refused with 409 rather than replaced: the first one is still open and can still receive money, so overwriting the row would orphan it silently.

Parâmetros

Corpo da requisição

ProviderAccountRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Move value between two accounts inside one processor

Move float out of this tenant's account at `provider_id`.

⛔ **The source is the binding named in the path**, and the driver resolved from it is authenticated as that account. There is deliberately no source field on the body: a cross-tenant debit would then be one mistyped value away, and such a debit reconciles to zero on both sides, which is what makes it nearly invisible.

This is a **treasury** operation, not a customer payment. A transfer between two customers is a ledger movement on the head and involves no processor — what this moves is the fiat float backing a tenant's ledger balance, so that each processor account matches the mirror that proves it.

⚠️ `authorized: false` means the processor is holding the transfer for an out-of-band human approval. The value is queued either way; do not re-send.

Parâmetros

Corpo da requisição

ProviderAccountTransferRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Read a tenant's QBRL minting policy binding

The tenant's policy binding, or 404 when it has none.

Parâmetros

Respostas

Bind a tenant to its own QBRL minting policy

Provision a tenant's own QBRL minting policy on a **running** head.

Under the shared-head tenancy tier a tenant's money is distinguished only by its minting policy, so this is the act of onboarding one. It generates the tenant's issuer keypair, derives the native `sig` script and its policy id, records the binding and creates the tenant's supply GL node.

Idempotent by construction — a repeat call returns the same policy id with `provisioned: false`, and no `Idempotency-Key` is required because the binding write is conditional on the policy already matching. A second, *different* policy for a tenant is refused with 409 rather than replacing the first: value already minted under the old one would still be on the head and would read as a foreign token.

This does not mint. Where the faucet's elastic supply is armed, the tenant's first funded transfer mints its opening balance under the policy bound here.

Parâmetros

Respostas

Read a tenant's quota and current usage

The effective quota, where it came from, and how much of today is spent.

Parâmetros

Respostas

Set a tenant's quota overrides

Raise or lower what one tenant may spend on metered Foundry work.

⚠️ **Absence is the estate default, not zero.** A tenant with no row here is a tenant nobody has priced yet, which is the opposite of how an unbound QBRL policy resolves — and right for the same reason stated in reverse: there is a safe default for a compile allowance and there is none for *whose money is this*.

**The meter ships; the pricing does not.** What a compile hour is worth, and which tenants get how many, is a commercial decision owned by the founders. This route is how that decision is applied once it is made.

Parâmetros

Corpo da requisição

TenantQuotaRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

List a tenant's inbound provider routes

Every provider connection whose inbound credits belong to this tenant.

An empty list is the honest answer for a tenant with no routes, and it is the state every tenant starts in: with no rows provisioned, inbound routing answers through the incumbent chain exactly as it always has.

Parâmetros

Respostas

Assign a provider's inbound credits to a tenant

Record which tenant receives inbound credits through a provider.

A provider-authenticated webhook carries no bearer, so the tenant a credit belongs to cannot come from a caller — it comes from the provider binding, and until this row existed a binding could only name the environment's own tenant. Writing it is what lets a non-incumbent tenant receive money.

Idempotent — a repeat call returns the same binding with `provisioned: false`, and no `Idempotency-Key` is required because the write is conditional on the owner already matching. A **second, different** tenant for one `(rail, provider_id)` pair is refused with 409 rather than replacing the first: a provider id identifies exactly one tenant, and silently rerouting it would move a live inbound stream into another ledger. Two tenants on the same processor use two provider ids.

Parâmetros

Corpo da requisição

ProviderRouteRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

List a tenant's transfer templates

This tenant's templates, current version each, newest change first.

RETIRED templates are listed: retiring gates new execution, never observation.

Parâmetros

Respostas

Author a tenant transfer template

Author, or supersede, one tenant-scoped transfer template.

The body is validated by calling the **same** `_parse_template` the committed `transfer_templates.json` is parsed by, so a tenant-authored template is held to every invariant an operator-authored one is. Versions are immutable and content-hashed: `template_version` must be strictly greater than this tenant's current version for the id, and the new version becomes current (D2). A colliding id — a platform template's name, or a version that does not supersede — is refused here, so the ambiguity never exists at execute time.

Parâmetros

Corpo da requisição

TenantTemplateCreateRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Get a tenant transfer template

One template's current version plus every version ever recorded.

A retired version still resolves here, and deletion has no code path at all — an obligation whose `template_content_hash` no longer resolves is an audit hole.

Parâmetros

Respostas

Retire a tenant transfer template

Retire the current version: no new execution, still readable.

`RETIRED` is the only accepted status — a rejected `ACTIVE` is the model's `Literal`, i.e. a 422 from FastAPI. Idempotent: a repeat answers 200 with the already-retired row. Reactivation is a new version (D2's supersede path).

Parâmetros

Corpo da requisição

TenantTemplateStatusPatchRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas