@konstantdotcloud/boombox

The developer kit for Boombox — turn existing software, data, models, workflows, and research into governed AI Products and Capabilities. Run them in the estate you choose, expose them through apps, APIs, MCP, agents, or workflows, operate them with identity, lifecycle, receipts, recovery, and observability, and selectively compose them into a consented capability network.

A cassette is one product shape: a repeatable governed workflow with typed inputs, executable steps, an output gate, and receipts. The CLI initializes the project, connects existing capabilities, asks Gary, ingests files, manages runs, and serves the developer surface over MCP. The SDK and local MCP tools validate and plan portable frontend+harness applications and durable workloads.

Connected Boombox use always starts with an authenticated developer or automation identity. Its credential is sent only to the explicitly enrolled gateway for authentication and never becomes repository content, Need content, telemetry, or a generated artifact.

The hosted surfaces are deliberately split. https://boombox.konstant.cloud is the public boombox-cloud front door for browser login and the closed builder-workspace routes (developer_workspace on the wire) for contract discovery, project attachment, Needs, and evaluation service facts. Its route adapter accepts only the declared method/path shapes; it is not a proxy to arbitrary Konstant APIs. Konstant support reads and Need responses use separately authenticated operator routes on https://konstant-v2.fly.dev, with an explicit exact-origin allowlist. Company-account control gateways and runtimes are additional, separately enrolled targets. None of these hosts turns authentication into company or operator authority.

Package installation/help plus repository scan, compile, and Product-local proof run without a credential because they create no remote Boombox state. SDK validation/planning may also run offline when authorized host code already supplies an exact canonical target; first-time consumer target composition waits for generated product_mcp rather than asking for internal identity. That local utility is not an anonymous platform session: every networked SDK, CLI, or MCP read or write requires authentication.

This kit is for consumer-side Product builders. It helps you use Boombox from your own repository; it does not make you a Boombox-core developer or ask you to design platform tenancy. Start with the Product outcome. The authenticated Product account supplies Boombox's internal isolation binding automatically; placement separately describes whether the Product runs in the owner's cloud, a customer's cloud, or a Konstant-managed target. If no authorized connection exists, the agent returns the truthful account-administrator continuation while safe local work continues.

Company context, evaluations, research, telemetry, and the Platform Need return channel are optional enhancements; their absence or failure does not block the safe local Product path. Refuse only the unsafe operation at a real company/customer-data, secret, provider-mutation, external-effect, billing, publication, or promotion boundary, and always return the smallest concrete way to continue.

A builder workspace can attach its reviewed Build Intent and opaque project continuity, submit/list/hydrate its own Platform Needs with agent-authored working context, return payload-free evaluation service facts, and report bounded SDK-usage signals. It has no company catalog or data, secrets, compute, billing, deployment, or invocation authority. When a Product needs live company/runtime access, use its separately authorized Product account connection. The CLI does not transfer workspace Needs or authority into that account.

Boombox Product owners and Capability providers are domain authorities. You keep the product, research, methods, evidence meaning, workflow, customer relationship, graders, and promotion decisions. Boombox supplies reusable deployment, operating, composition, observability, and distribution rails. When a reusable platform seam is missing, the developer kit can return an actionable Need with the working context required to build it while a clearly labeled local adapter keeps the Product moving.

Quickstart — connect a source code project

Start with the outcome:

Put this workflow on Boombox and get it running. Reuse the frontend and harness already here if they fit. If a small UI is missing, help me build it. Ask me only for decisions you cannot determine safely from the repository.

You do not need to choose a Boombox Product shape or enumerate platform services. The installed skill infers the shape and carries the same request through local proof and every authorized connected action.

1. Install and initialize the exact local package

Install without running dependency lifecycle scripts. Project initialization installs the package-pinned skill and prints separate scan and builder MCP connections; it writes no credential and changes no application code:

npm install --save-dev --save-exact --ignore-scripts @konstantdotcloud/[email protected]
node ./node_modules/@konstantdotcloud/boombox/dist/boombox.js project init . \
  --client codex --client claude --json

Install an exact reviewed version with lifecycle scripts disabled and keep it in the consumer lockfile. Invoke its explicit node_modules/@konstantdotcloud/boombox/dist/boombox.js entrypoint: do not use npx or a bare/global boombox at this boundary. Project initialization refuses unless the consumer-local package version equals the package instance executing initialization, its real CLI entrypoint remains inside the project, and the lock is exact. The skill is also available as boombox://developer/skill. The existing-codebase guide is served as boombox://developer/onboarding, and the evaluation guide is served as boombox://developer/evaluations, so the coding agent can inspect a legacy repository and map an existing runner without asking the developer to hand-author the ontology.

Project initialization returns scan_mcp, builder_mcp, product_mcp, scan_verify, builder_verify, and product_verify. Use the MCP commands unchanged; they bind one canonical --project-root and must never point at different checkouts. builder_mcp uses the builder workspace for continuity and Needs; product_mcp uses the separate Product-account config for authorized company/customer work. Treat each verify object as a required fragment of the discovery response, not as another tool call. Start only scan_mcp. Before reading repository content, call boombox_platform_describe({}) and compare the response with scan_verify: require the exact installed package_version, mcp.active_profile:scan, mcp.live_product_account_calls:false, and mcp.remote_mutation_tools:false.

2. Preview and configure this project's local profile

The agent proposes a closed boombox.project-profile.v1 input from the ordinary outcome and local evidence. It contains only the primary Product, repository-relative docs/entrypoints/harnesses/evals, reviewed commands, and declared deployment targets. A minimal input looks like this:

The primary_product.outcome sentence is also the Build Intent. It answers “what are you trying to make, and for whom is it useful?” in ordinary language. Local profile preview/configuration applies the same bounded text policy as attachment, so connecting later introduces no new sentence constraint. It stays local during scan/configuration; project attachment later shows and seals that exact sentence into the authenticated support and requirement-return channel.

{
  "primary_product": {
    "name": "workflow-console",
    "outcome": "A user runs the existing workflow and inspects its durable result",
    "shape": "portable_application"
  },
  "assets": {
    "docs": ["README.md"],
    "entrypoints": ["src/server.ts"],
    "harnesses": ["tests/harness.test.ts"],
    "evals": []
  },
  "commands": [
    { "kind": "local_test", "command": "npm test" },
    { "kind": "local_build", "command": "npm run build" }
  ],
  "deployment_targets": []
}

Invoke boombox_project_profile_preview with the proposed profile and instruction_targets:["AGENTS.md","CLAUDE.md"]. The result reports profile and instruction dispositions with writes_performed:0 and network_calls:0. After explicit confirmation, save the reviewed input to a bounded JSON file and configure it:

node ./node_modules/@konstantdotcloud/boombox/dist/boombox.js project configure . \
  --input ./boombox-project-profile.json \
  --instructions AGENTS.md --instructions CLAUDE.md

Omit --instructions to select both files. Configuration writes .boombox/project.json and atomically creates or replaces only the marker-bounded managed block in each instruction file. Repository-owned prose stays byte-for-byte outside that block; malformed markers, linked files, and path escape refuse before mutation. Never fork or customize the canonical build-on-boombox skill. Put project-specific facts in the profile and managed overlay.

Commit the reviewed .boombox/project.json and managed instruction changes so every context shares the same Project identity and Build Intent. Keep .boombox/handoff.json, .boombox/evaluations/, local attachment/retirement receipts, service-fact outboxes, locks, temporary files, and authentication state out of Git; package-owned local handoff, evaluation, and attachment writers add their durable state paths to .boombox/.gitignore. A lock, recovery fence, or temporary file retained after a crash is diagnostic evidence: do not stage it, and do not delete it until the interrupted operation has been inspected.

3. Scan, build, and prove the Product locally

Keep the credential-free scan context open while the agent chooses the smallest Product shape, implements the bounded slice, runs repository tests, and proves accepted, refusal, idempotency, recovery, and retirement behavior. Use application/workload validate and plan here only when the repository already contains an exact canonical target supplied by authorized host code. For a first-time target, prepare the Product descriptor and placement inputs, then use generated product_mcp; never ask the Product builder to author internal identity. For a cassette, finish the local spec, schema, and repository tests before a connected dry-run or publication. A green local plan is useful proof, not deployment authority.

The stopping point follows the requested outcome. For repository understanding or validation, local proof plus one exact continuation may be complete. For “get it running,” continue through the authorized application or workload lifecycle, inspect from a fresh session, retain the receipt, and prove recovery or retirement. Optional evaluation, program, corpus, and network-learning features degrade independently; the selected deploy or Run does not become optional merely because those enhancements are unavailable.

When returning a reusable gap is useful, scan may call boombox_need_draft. It writes at most 32 strict, stably ordered Needs to .boombox/handoff.json. Each draft uses seam_identity, observed_availability, delivery_continuity, requested_delivery action/priority, and one multiline working_context written by the agent from the work already done. The developer does not fill out a form.

The working context accepts up to 64 KiB of UTF-8 text and keeps the original ask, current task, company/Project/Product, repository root and revision, relevant paths and systems, attempts, commands/tests and material results, observed versus expected behavior, decisions and tradeoffs, constraints, and exact unblock. Natural Markdown may include paths, URLs, code fences, revision identifiers, and concise test output. Do not include secret or credential values, bearer tokens, private keys, signer material, or raw customer payloads, and do not dump a repository, transcript, or dataset. Need drafting does not require a Chronicle, session ontology, transcript-ingest path, or new permission system. Drafting failure leaves the local Product result unchanged.

4. Authenticate a builder workspace and attach the project

Stop only the scan MCP process before a connected action; preserve the developer's coding conversation and working context:

node ./node_modules/@konstantdotcloud/boombox/dist/boombox.js login
node ./node_modules/@konstantdotcloud/boombox/dist/boombox.js doctor
node ./node_modules/@konstantdotcloud/boombox/dist/boombox.js project attach . --client-class codex

Builder-workspace admission is authenticated but does not require a Product-account invitation: any principal accepted by the configured WorkOS/AuthKit sign-in can create or resume one narrow personal workspace. There is no anonymous hosted session, source access, company-data access, or runtime authority. When a live action needs an authorized Product account, follow the exact connection continuation returned by project configuration or doctor; the browser presents any authorized choices by human company label. Account connection and deployment placement are separate decisions. Ask where the Product should run only when owner cloud, customer cloud, or Konstant-managed placement cannot be inferred, and never ask the developer to invent an internal identifier or choose a Boombox tenant. Stop and restart the bridge with the returned config while preserving the coding conversation; a running process does not hot-switch authority.

Default login creates or resumes a builder workspace. Attachment is the standard supported connection. It shows and sends the one-line Build Intent already declared as primary_product.outcome, together with the opaque project reference, profile digest, exact package version, and client class. It never sends source, filenames, paths, commands, prompts, provider/region details, customer payloads, or arbitrary reasoning. The request digest and verified receipt make that declaration inspectable and revisioned while granting no Product-account or execution authority. An explicitly authorized Konstant support operator may see that verified Build Intent, opaque project/workspace anchors, lifecycle, package/client cohort, and bounded activity/Need counts. Compact project, inbox, and list projections contain no email, source, paths, prompts, customer/provider data, credentials, raw requests/evals, or Need prose. An audited operator show for one exact Need returns its sealed request, server-derived submitter/scope, project attachment, submission identity, and full working_context. The initial correlation key is the server-derived actor and workspace/tenant scope plus project attachment, immutable submission ID/time, and signed narrative. It recovers who asked, from which connected project, and in what work context without requiring a separate session-tracking service. Recover the receipt with project get .. Attachment, context, evaluation, telemetry, or return-channel failure never blocks safe local Product delivery. When the project no longer needs this continuity binding, inspect it with project get ., then retire that exact attachment with project retire . --confirm-receipt-digest <receipt_digest>. The verified tombstone is retained locally; retirement does not delete the repository or grant tenant/runtime authority. With project get --json, the response is {attachment, drift, remedy}. Scripts passing project retire --confirm-receipt-digest read the digest from .attachment.receipt_digest.

Builder-workspace credentials are independently revocable. A bearer can inspect and revoke only its own metadata:

node ./node_modules/@konstantdotcloud/boombox/dist/boombox.js credentials list
node ./node_modules/@konstantdotcloud/boombox/dist/boombox.js credentials revoke <credential_id>

Use the exact ID returned by credentials list; a bearer cannot enumerate or revoke peer devices. Revoking the credential used by the current machine removes its local login only after the server confirms revocation. To recover after losing a device or every local credential, run login again. The authenticated browser flow offers same-principal, exact-one recovery when the workspace has reached its credential limit, so a lost machine cannot permanently lock the developer out.

5. Reconnect the builder MCP in the same coding conversation

For project continuity and Needs, start the returned builder_mcp at the same project root. Run boombox doctor --require developer_contract,need_return,project_attachment, adding evaluation_fact only when this Product is returning evaluation service facts. Then call boombox_platform_describe({}), and compare the response with builder_verify. Restart the MCP process after every credential, identity-scope, account, or gateway change while preserving the coding conversation; a running process never hot-switches authority. If the config directory watcher fails asynchronously, serve --mcp continues with its file watcher; if both watchers fail, the bridge stays up, logs one bounded line per failed watcher, and requires explicit reload for later config changes.

For authorized company/customer data or runtime work, run login --account, start the returned product_mcp unchanged, and compare boombox_platform_describe({}) with product_verify. The Product-account config is separate from the builder-workspace config; neither connection inherits the other's authority.

Both generated connected verification objects require gateway_contract.status:verified from the MCP process's startup negotiation; restart that process to refresh the observation. product_verify also requires connection.kind:product_account, product_account.label_status:configured, a display-only human label, and hidden internal identity. If verification reports unavailable or incompatible, do not claim the connected action; follow its exact continuation while local Product work continues.

Before any connected action, read product_account.label from discovery and confirm that its human name matches the Product account intended by the current work. A mismatch means reconnect by human label; never repair it by entering an internal identifier.

For a drafted Need:

1. boombox_need_preview returns the complete request plus a local boombox.need-approval.v1 envelope. The approval binds the exact need_key, request_digest, handoff generation, and project attachment without a network call.
2. boombox_need_submit requires need_key, approved_request_digest, and approved_approval_digest, recomputes the approval, refuses local drift before transport, performs an authenticated idempotent round-trip under capability.request, and binds only the matching receipt.
3. On every relevant fresh builder, boombox_need_list rediscovers open/answered work for the authenticated scope. Follow the opaque cursor while truncated is true.
4. boombox_need_get hydrates only relevant IDs returned by list, including the full working_context. Never bootstrap from a pasted ID.

For a builder workspace, a first Need submission and every new or changed Need context require the current verified project attachment. Login by itself is not enough. An exact already-committed request may replay under its complete superseded attachment binding after response loss, and historical list/get remain available under that same binding; neither path may create or revise a Need. A retired or missing attachment leaves local drafting and Product work available but makes connected preview/submit/list/get return the exact attachment continuation instead of silently broadening scope.

A typed platform_resolution binds the exact Need and Need digest, package version/digest, gateway contract/protocol/release digests, feature and contract references, conformance entrypoint, migration-instruction digest, and optional local-adapter retirement condition. It carries execution_authorized:false. Verify the exact installed package, live gateway contract, and local compatibility tests before retiring the adapter. Submission or resolution alone does not create a branch, PR, merge, release, deployment, or effect.

When the Need is owned by boombox_platform, a caller may separately request requested_delivery.action:'draft_github_pr'. The bounded responder outcome is a draft_pr_ready message plus a stable draft_github_pr artifact reference for review. It remains non-authoritative: the original receipt keeps github_pr_created:false and execution_authorized:false, and neither request nor response performs Git, creates or merges a PR, publishes a package, deploys, or retires an adapter.

The Need service derives scope and actor, uses durable idempotency/rate/capacity admission, and fails closed on storage failure. Its content-addressed receipt is an integrity acknowledgement inside the Need chain, not a signature, Product evidence, provider attestation, or execution authorization. The responder uses need.respond for typed compare-and-swap reply, question, answer, resolve, and decline transitions. Terminal closure and capacity release commit together.

Every builder-workspace request, receipt, thread, and list filter binds the exact attachment revision under which it was accepted. A first/new Need or changed request must use the current revision; a superseded revision supports only exact committed replay and historical read continuity. A Need's stable identity binds the workspace, stable project attachment ID, and Need key, so its thread survives a profile revision without colliding with another project. Each accepted revised request remains a distinct immutable submission.

External local orchestrators can import the same strict handoff contract and read/write/bind helpers from @konstantdotcloud/boombox/handoff; those helpers never authenticate, call a provider, or run Git. Signed Needs already stored by an earlier cohort remain readable and verifiable byte-for-byte. Ignored local draft handoffs are package-local working state, not platform evidence; regenerate them with the current scan before a new submission. Exact response-loss replay applies to a request already committed by its compatible gateway cohort.

Use the generated Product-account connection only when the next operation requires company or runtime authority. Every deployment, invocation, secret, data, billing, cassette, Gary, and admin action still requires its exact advertised permission. When HomeBase is enabled, the MCP prompt boombox_company_operating_brief may instruct the local agent to combine authorized Gary context with recent Runs, open Needs, and available lifecycle/health/receipt reads. It is a read-only guidance prompt, not a tool that performs those reads itself. The agent labels plans as intent, current records as operating evidence, and missing sources as unavailable. Missing company context never blocks repository-only work.

node ./node_modules/@konstantdotcloud/boombox/dist/boombox.js login --account

The browser presents authorized Product accounts by human label; the connection stores the internal identity. Runtime owner, cloud project, region, residency, and billing remain separate explicit Product placement inputs.

The canonical path is outcome → install/init → profile preview/configure → scan/build/prove locally → builder-workspace login/attach → reconnect builder_mcp in the same coding conversation → optional Need preview/submit/list/get and payload-free evaluation return → optional Product account connection for company/runtime authority. Platform operations are a separate Konstant surface whose individual operations still enforce their exact credentials and grants:

| Tool | What it proves | |-|-| | boombox_platform_describe | Reports the current scan/builder contract, package version, active profile, and network/mutation posture. | | boombox_project_profile_preview | Validates the bounded local profile and previews managed instruction dispositions with zero writes and zero network calls. | | boombox_project_configure | Builder/internal ops, local only. After write_confirmed:true, CAS-updates the profile and replaces only managed instruction blocks. The project-local CLI provides the same configuration path before login. | | boombox_project_attach | Authenticated builder workspace. Attaches the reviewed one-line Build Intent plus opaque project/profile/package/client metadata and returns a receipt with no Product-account or execution authority. | | boombox_project_get | Authenticated builder workspace. Recovers the verified attachment for the exact local profile without returning a bearer or Product-account grant. | | boombox_project_retire | Authenticated builder workspace. Retires only the exact attachment receipt digest the caller confirms and returns a verified tombstone with no Product-account or execution authority. | | boombox_need_draft | Scan only. Atomically writes the complete strict multi-Need local handoff. This is a repo-local generated-file mutation, not a network, provider, Git, issue, PR, or deployment action. | | boombox_need_preview | Builder/internal ops, local only. Returns the exact selected request, including its rich working_context, and the local approval envelope binding request digest, handoff generation, and project attachment. approval_required:true requests an MCP-client decision; it does not attest human or out-of-band review. | | boombox_need_submit | Authenticated builder/internal ops. Requires the exact caller-confirmed Need key, approved request digest, and approved approval digest; submits the authenticated request, verifies its receipt identities/digests, and records that exact binding locally. Client policy may require a person or permit authorized automation. | | boombox_need_get | Authenticated builder/internal ops. Reads one sealed scope-bound Need with its complete current request and working_context, messages, artifacts, and lifecycle state without granting mutation or execution authority. | | boombox_need_list | Authenticated builder/internal ops. Lists at most 50 newest-first open/answered summaries plus a nonnegative corrupt count and opaque continuation cursor, without returning message prose, request context, source, evidence, prompts, or artifact references. | | boombox_application_validate | Validates a portable frontend+harness descriptor against the connected Product account plus declared runtime placement, and reports whether an opaque product qualification pair is declared. It does not fetch or semantically accept that record. | | boombox_application_plan | Produces the public SDK's side-effect-free application plan; production without qualification refuses. It cannot apply, promote, rollback, or retire, and records a fixed non-authoritative local planner identity rather than a caller-authored audit actor. | | boombox_workload_validate | Validates an immutable Product worker descriptor against the connected Product account plus declared provider placement, residency, custody/billing, runtime store, cost cap, and retention. Internal isolation paths are compiled behind the Product MCP. | | boombox_workload_plan | Produces a deterministic, provider-free workload authoring plan; it cannot apply, trigger, attach, retry, reconcile, or observe a provider. |

Durable job authors import defineWorkload, defineWorkloadTarget, and planBoomboxWorkload from @konstantdotcloud/boombox/workloads. Those functions deliberately stop before runtime authority. A green plan proves the declared seam and refusal checks, not that tenant admission, provider execution, recovery, or operator reattachment is live.

An admitted service composition may additionally use createBoomboxWorkloadControlClient() from the same entrypoint. The client derives exact apply/invoke intent digests, calls the authenticated workload host, validates response identity plus exact admission/lifecycle receipt context, binds the returned run id to the requested logical run key, keeps its deadline active until the complete bounded response body is read, performs no automatic mutation retries, and keeps observer credentials separate. Product-terminal reads bind receipt digests to the projected immutable result and product-receipt custody. It does not mint authority: callers must inject purpose-token and observer-credential providers backed by the tenant control plane. Without those providers, return the local plan and the missing authority seam rather than treating a static API key as workload admission.

Application authors import defineApplication, defineApplicationTarget, and planBoomboxApplicationDeployment from @konstantdotcloud/boombox/apps. Production descriptors carry only the product-owned opaque { qualification_ref, qualification_digest } pair. The product keeps the qualification schema, evals, floors, claims, expiry, and evidence meaning; Boombox never copies those semantics into runtime state. A composition root injects one tenant-authorized BoomboxApplicationQualificationVerifier whose pinned authority names the exact trust policy and verifier release. Apply and every promote or rollback operation call it before provider work and require a payload-free verification receipt bound to the tenant, exact full deployment target, artifact, manifest, and attestation. Inspect, lifecycle receipts, and the signed fleet projection preserve that binding. An unqualified preview is permitted only as explicitly unqualified and cannot inherit qualification evidence from another Release.

Before wiring a product verifier, run runBoomboxApplicationQualificationVerifierConformance() with one exact accepted case plus explicit expired, product-release-mismatched, placement- mismatched, and other product-owned refusal cases. The black-box report retains only immutable digests and refusal facts; product records and customer payloads stay inside the product boundary. This conformance helper proves the verifier contract, not that a particular artifact is qualified or deployed.

Boombox exposes application descriptor/target authoring, local validation/planning, verifier conformance, and createBoomboxApplicationLifecycleClient from @konstantdotcloud/boombox/apps, whose apply/inspect/retire use the host's /api/v2/applications/* routes. The export exists; it does not grant builder authority. Those routes require the Product account's lifecycle authority, and a developer-held credential never satisfies them. Compose the client under account-authorized operator composition, never developer-held auth; internal or manual lifecycle evidence does not widen the developer contract.

Admit a cross-account application caller

The callee owner first deploys a standing Cloud Run target with peer_ingress.mode: 'iam_invoker_federation'. A tenant-admin Product-account credential can then grant one account-bound admission. The principal may be a service account in another GCP project; the callee service itself must remain in a project admitted by the host manifest.

boombox admissions grant \
  --callee <deployment_id> \
  --account tenant:<account> \
  --principal serviceAccount:<name>@<project>.iam.gserviceaccount.com \
  --transitions capability,status,ask

boombox admissions list --callee <deployment_id>
boombox admissions revoke --callee <deployment_id> --admission <admission_id>

Grant and revoke synchronously refresh the existing callee deployment. A grant becomes active only after the exact Cloud Run invoker set is verified and its invoker_binding is applied; a failed reconcile stays pending and returns a typed code plus its smallest continuation. Repeating an already-applied grant is an idempotent no-op. Revocation removes the admission principal on the same exact-set reconcile.

Inside the callee, createInjectedLifecycleClient(runtime).listAdmissions(deployment_id) reads active admissions with that deployment's injected operation credential. The method never accepts a Product-account credential for the injected read lane, and a credential bound to another deployment returns a typed 403 client error.

Give your application end-user login

Declare end-user login beside the application's secrets and events, and bound the standing Cloud Run target:

const descriptor = defineApplication({
  // ...existing application fields...
  end_user_ingress: { mode: 'host_front_door', session_ttl_seconds: 28_800 },
  end_user_access: {
    allowed_orgs: ['workos:org_01EXAMPLE'],
    allowed_email_domains: ['example.com'],
    open_to_tenant: false,
  },
});

const target = defineApplicationTarget({
  // ...existing standing cloud_run_service target...
  scaling: { min_instances: 0, max_instances: 10, concurrency: 80 },
});

host_front_door requires a standing cloud_run_service and an explicit scaling.max_instances from 1 through 1000. The platform owns the login front door, hub, application serving origin or fallback path, DNS, IAM hop, session, and public-key injection; the application only declares access and verifies each request.

import {
  BOOMBOX_END_USER_ASSERTION_HEADER,
  verifyBoomboxEndUserAssertionFromEnvironment,
} from '@konstantdotcloud/boombox/apps';

const assertion = request.headers.get(BOOMBOX_END_USER_ASSERTION_HEADER) ?? '';
const principal = await verifyBoomboxEndUserAssertionFromEnvironment(assertion);

The verifier composes both the injected public keys and the exact deployment-generation audience. Authorize the end user and acting_for mandate against Product-owned records; organization means an IdP org-admin/role claim or explicit organization consent, never membership alone. Map the namespaced org_ref to a retained Product authorization record. tenant_id identifies the deploying estate and is never the authorization subject. Read routes may ignore jti; write routes atomically deduplicate it before the effect or require a fresh assertion.

For a tier-1 local loop, explicitly compose the throwaway signer with the parameterized verifier:

const signer = await createLocalDevelopmentEndUserSigner();
const assertion = await signer.mint(localClaims);
const principal = await verifyBoomboxEndUserAssertion(assertion, {
  verificationKeys: signer.verificationKeys,
  expectedAudience: localClaims.aud,
});

The signer generates its own P-256 keypair and forces assurance: 'local-development-only'. Its assertions fail against real injected keys and cannot represent platform verification.

Application event subscriptions

A standing cloud_run_service descriptor may subscribe under its own harness API prefix:

event_subscriptions: [{
  kinds: ['workload_run.terminal', 'subject_head.advanced'],
  path: '/harness/events',
}]

Every delivery carries the same canonical, payload-free boombox.application-event.v1 envelope, bounded to 4 KiB. Read x-boombox-event-signature, x-boombox-event-kid, x-boombox-event-delivery, x-boombox-event-attempt, and x-boombox-event-first-delivered-at, then call verifyBoomboxApplicationEvent(envelope, signature, kid, { verification_keys: [runtime.peer_authority_verification] }). The head source names subject_kind, head_seq, head_digest, and nullable previous_head_digest; the terminal source names the run, job, subject, job_revision_digest, and closed terminal_state (succeeded, failed, or cancelled). Either source may carry a strict cause made only of bounded ids/refs.

Delivery is at-least-once: durably deduplicate on stable event_id; delivery_id identifies one attempt. Any 2xx acknowledges and its response body is ignored. tenant_id is the platform scope; Product namespaces live in fetched data, not the envelope. The envelope is only a pointer, so fetch details through existing authorized application reads. Observers inspect recent attempts and terminal undeliverable receipts at GET /api/v2/applications/:deployment_id/events.

Test application capability calls offline

Import createMockBoomboxAppRuntime from @konstantdotcloud/boombox/testing, declare each peer verb and its input_schema, register the application event handler before calling the verb, and use the returned fetch as the consumer transport. A successful verb response registers its terminal delivery immediately; a settled delivery failure is claimed by the next mock transport interaction. Always await runtime.flushEvents() after the verb call: flushEvents() is the synchronization point that proves every scheduled delivery settled or throws its typed failure.

An unclaimed or pending delivery failure is written to stderr at process exit and changes an otherwise-successful process.exitCode to 1; a consumer unhandledRejection handler cannot swallow that failure. Use terminal_event_delay_ms only to simulate asynchronous timing. Correctness must depend on durable ordering and flushEvents(), never on a chosen delay. The complete offline path is at examples/consumer-app-full-loop from the Konstant repository root; npm consumers use the @konstantdotcloud/boombox entrypoints shown there.

Develop locally against a live application

The callee owner explicitly declares up to eight exact Google principals in peer_ingress.developer_invokers and applies the iam_invoker_federation target. An authenticated Product-account developer for the application's own tenant—using an operator-seat or tenant-admin credential—then runs boombox app dev-token <application_id> and sends two headers to the callee: X-Serverless-Authorization with the standard Bearer scheme applied to the output of gcloud auth print-identity-token --audiences=<app url> for the declared Cloud Run principal, and x-boombox-peer-assertion with the dev-token output for application authority. The short-lived host-signed assertion records sub: developer:<key_id> and subject_kind: developer; the route refuses when the callee has not elected developer access.

Application secrets and service availability

Declare each secret reference with the environment name that should receive its file path; the value never enters the descriptor, code, image, environment, or logs:

{
  "secret_refs": [
    {
      "ref": "<SECRET_REF>",
      "residency_class": "<RESIDENCY_CLASS>",
      "region": "<REGION>",
      "env_file": "SECRET_VALUE_FILE"
    }
  ]
}

The operator creates the secret and value version in the application's cloud project, then places the matching binding in application_runtime in the host manifest:

gcloud secrets create <SECRET_ID> --project=<PROJECT_ID> \
  --replication-policy=user-managed --locations=<REGION>
gcloud secrets versions add <SECRET_ID> --project=<PROJECT_ID> --data-file=-

{
  "secret_bindings": [
    {
      "ref": "<SECRET_REF>",
      "kind": "gcp_secret_manager",
      "project": "<PROJECT_ID>",
      "secret_id": "<SECRET_ID>",
      "residency_class": "<RESIDENCY_CLASS>",
      "region": "<REGION>"
    }
  ]
}

Apply pins the latest enabled numeric version and injects only its mounted file path under SECRET_VALUE_FILE. Rotation is version-add followed by boombox app refresh <deployment_id>: refresh re-evaluates the active admitted descriptor and target, rolls provider state only when convergence requires it, records a refresh receipt, and leaves an unchanged deployment on the same revision. Running revisions are never silently re-keyed. APPLICATION_SECRET_BINDING_NOT_FOUND means the operator creates the missing store object and adds the manifest binding; SECRET_MANAGER_VERSION_UNAVAILABLE means no enabled value has been placed; and APPLICATION_SECRET_RESOLUTION_UNSUPPORTED continues on a standing staging cloud_run_service in standing_targets[], not preview or boombox_vm.

FALLBACK — until secret_refs, or for local development. An application in its own cloud project may read its store directly at boot with ambient identity:

import { SecretManagerServiceClient } from '@google-cloud/secret-manager';
const store = new SecretManagerServiceClient();
const name = process.env.SECRET_VERSION_REF!;
const [version] = await store.accessSecretVersion({ name });
const value = version.payload?.data?.toString('utf8');

This fallback is not portable and is not per-app-isolated. Prefer secret_refs whenever the host supports it, and never place a secret value in a descriptor, image ENV, or code.

Choose by traffic and latency promise: preview is disposable and TTL-bound; standing availability: 'on_demand' is durable, scale-to-zero, and may cold-start; standing availability: 'always_on' keeps a warm floor. on_demand requires scaling.min_instances: 0; always_on or an omitted availability requires at least 1.

Released runtime lane facts: boombox_vm and standing cloud_run_service receive their operation credential as token_file; bounded Cloud Run preview uses not_provided_v1; staging forbids a preview block; production requires a declared qualification. Standing Cloud Run targets have no preview TTL or cost cap, keep their artifact under allowed_repository_roots, and require standing_artifact_hosts only when a standing boombox_vm target is present. Admission refuses target, artifact, and availability-floor drift before provider apply with APPLICATION_TARGET_NOT_APPROVED, APPLICATION_ARTIFACT_NOT_APPROVED, APPLICATION_STANDING_SCALING_NOT_ALWAYS_ON, or APPLICATION_ON_DEMAND_SCALING_NOT_SCALE_TO_ZERO.

A descriptor may optionally pin a product-owned semantic-admission context schema and verifier release. Invoke then supplies only an opaque placed context reference and claims digest. The host verifies placement, calls the product verifier with frozen input and narrow authenticated identity, independently reads and byte-verifies one exact accepted/refused receipt generation in customer custody, and creates no logical run or provider call on refusal. The accepted proof enters the host admission receipt and worker boundary. The public client returns that product outcome as BoomboxWorkloadProductAdmissionRefusalError, exposing only its bounded product-owned reason code and host-verified immutable receipt reference. It does not expose a raw host/provider body, payload, or credential, and only the exact domain-refusal HTTP status can produce that typed result; a platform failure with a lookalike body remains generic and redacted.

runBoomboxWorkloadProductAdmissionVerifierConformance() proves exact repeated acceptance plus explicit stable product-owned refusals without importing product semantics into Boombox. verifyBoomboxWorkloadRunAdmissionReceiptForContext() supports the separate worker-side check of the already-issued host receipt before product code begins. Products implement those adapters and remain authoritative for their claims and receipt meaning; Boombox supplies authenticated admission, placement/custody verification, execution, recovery, and host receipts for the current operating arrangement. The generic worker verifier proves host-receipt integrity and exact context; the product adapter must additionally reject a still-valid product proof that is semantically stale or mismatched.

The MCP transport is the local stdio bridge. Its stdout is reserved for JSON-RPC; diagnostics use stderr. scan is offline, with builder authenticating in a separate working context at the same canonical root. Platform administration is a separate operator-configured surface and does not grant authority by profile selection. The authenticated build route is the single instrumentation point for MCP, CLI, and other admitted clients; the MCP is not a privileged telemetry side door.

cassettes build stages the actual Product spec in the tenant's private draft store. Its best-effort activity event is deliberately smaller: server-derived cassette/schema/spec digest and draft/revision, a bounded caller-declared toolchain/version, content_included:false, and storage_semantics:best_effort_activity_log. The declaration is useful funnel context, not client attestation. Caller-supplied source filenames, prompts, keys, and arbitrary telemetry fields are discarded. The tenant draft remains authoritative Product state; richer connected capture requires the tenant's explicit learning policy and grant.

Evaluation is local first

Import the common evaluation contract from @konstantdotcloud/boombox/evaluations when an existing local harness needs portable lineage. Keep the existing runner and map only facts it really knows to Subject, Claim, Case and Case set, Context binding, Configuration, Execution, Observation, Judgment, Outcome, Comparison, and owner Decision. Bind exact Project, Product, Capability, Surface, Release, Deployment, and Run references.

Use granularity:'case', a present Case slot, and the real Case Set for the declared claim. A genuinely standalone episode uses a singleton set with denominator one; a case within a predeclared suite may bind that exact wider population, while its Observations retain their own honest denominators. The case record alone does not establish a route, selector, causal, cohort, or population claim. Such a claim uses a separate granularity:'aggregate' record, marks Case absent with reason:'not_applicable', and binds the complete decision population. Preserve an explicit unknown denominator or return a typed incomplete mapping when that population is not recorded; never substitute a convenient singleton, mix populations, invent a synthetic suite case, or report only selected successes. Create present JSON references from the real verified values with createBoomboxEvaluationJsonReference(); a missing mandatory source produces a typed, nonblocking mapping_incomplete continuation rather than a fabricated URI or digest.

Capture progresses in three explicit levels:

1. local_only keeps the sealed record under repository or owner-cloud custody and is the default. Seal and verify it, then use tryRecordBoomboxEvaluation() for a private ignored .boombox/evaluations/ recovery journal whose failure cannot replace the Product result.
2. service_fact uses tryCompileEvaluationServiceFactFromLocalEvaluation() to derive a transient attached variant internally and return only a payload-free operational discovery fact from the canonical sealed local record, exact local profile, and verified project-attachment receipt. It cannot carry the rich evaluation envelope, buckets source occurrence to a UTC hour, and is not Product evidence, a grader result, outcome, or promotion. Optional job_id, subject_id, run_id, and head_digest fields correlate the fact with a registered runtime subject while keeping the projection payload-free. When the developer credential grants evaluation.fact and boombox_platform_describe({}) reports improvement.evaluation_atlas.service_fact_transport:'available_with_evaluation.fact_grant', use createBoomboxDeveloperWorkspaceEvaluationServiceFactClient() after ordinary boombox login; it loads the developer credential inside the composition root, pins the first receipt to that workspace, and never returns the bearer to Product code. Trusted service/CI hosts may use the lower-level createBoomboxEvaluationServiceFactClient({base_url, authorize}) authority port. Wrap append with tryDeliverBoomboxEvaluationServiceFact() to persist the exact fact before network access; a response-lost delivery resumes with tryResumeBoomboxEvaluationServiceFactDelivery(), which first reads by deterministic bbevf_* identity and the stored historical attachment binding. Pending entries are discoverable through listPendingBoomboxEvaluationServiceFactOutboxEntries(). If the attachment advances before a pending fact is accepted, compile the semantically identical fact against the new receipt and call tryRebindBoomboxEvaluationServiceFactDelivery(): it reads the historical identity first, permits a successor only after exact typed NOT_FOUND, requires the same stable project and a strictly newer attachment, and retains predecessor/successor lineage so acceptance of either resolves recovery. The delivery result unions make one bounded attempt at a time and report product_work_blocked:false; adapter code must still catch journal, compile, and pending-list errors and preserve the Product result itself.
3. learning_grant_ref requests rich connected capture. A local grant reference is never authority; the connected service must verify the effective grant before accepting any rich record. The capture grant remains distinct from product_learning_authority_ref. Its required service_fact boolean independently keeps or declines the payload-free lane while rich authorization is evaluated; it does not authorize rich capture.

Builder-workspace usage events have a server-enforced 90-day TTL. Evaluation service facts are currently retained without a TTL. That is current storage behavior, not indefinite learning permission: richer capture or broader use requires explicit retention, deletion, legal-hold, and derived-use policy before it ships.

The Product owner controls domain schemas, cases, graders, floors, outcomes, evidence meaning, extensions, and every qualification or promotion decision. Context binds by authorized class, immutable reference/digest, freshness, scope, and custody; it carries no raw source, prompt, transcript, payload, or evidence bytes and grants no read authority. Evaluation, context, Chronicle, research, telemetry, or learning-service failure never blocks a safe Product validate, plan, deploy, run, inspect, or retire path.

Read the package-shipped references/evaluation-ontology.md guide or invoke the MCP prompt boombox_map_existing_evaluations for repository-specific guidance. Evaluation mapping is SDK authoring plus an MCP guidance prompt: the MCP exposes no rich-evaluation append, mutate, qualify, or promote tool. The only connected evaluation transport in this cohort is the optional payload-free service-fact SDK lane described above. Jest, Vitest, Pytest, Promptfoo, a custom harness, human review, or a business-outcome system remains the runner and semantic authority.

For a long-running ablation or research program, keep the Product's existing program_id and append-only scientific DAG. The Product store remains authoritative for hypotheses, membership, branches, joins, evidence meaning, outcomes, and decisions. The planned connected program projection will index immutable refs to Evaluations, Runs, Releases, configurations, receipts, and freshness so a fresh MCP session can reopen the work; reading that index will not grant evidence-handle access. Until that service is advertised, reopen locally and return one typed Need without blocking the program.

A current lightweight ablation record that may carry raw inputs/outputs and lacks stable evidentiary identity remains Product development evidence. Project only its immutable artifact reference as an Observation using BOOMBOX_EVALUATION_COMPONENT_CONFORMANCE_OBSERVATION_KEY; do not treat it as preregistered, causal, qualification-eligible, or training-eligible evidence. Material work freezes and contextually verifies the Product's real experiment spec and immutable experiment record. Record kind alone grants no Atlas, qualification, promotion, or training eligibility; durable Run composition remains a separate advertised lifecycle integration.

Training is a separate optional chain: Product Program Event -> Product-labeled Learning Example -> purpose- and grant-bound Learning Corpus View -> immutable selected-plus-excluded Corpus Manifest -> durable Training Run -> Product eval/floor and promotion decision. A Run, trace, receipt, service fact, or corpus exclusion is not a label. Raw material and full manifests stay in declared custody; common refs/digests make authorized records joinable, and owner-published compatibility artifacts decide whether labels from different Products or customers may share a corpus. No connected corpus or training API is claimed by this package yet.

Loading a harness — pick a shape

You have a capability in another codebase — a harness: pure core, typed commands, self-describe, evals. Boombox maps it to one of four Product shapes. A Product may also use the optional subject-runtime primitive when durable per-subject snapshot reduction fits. Pick the smallest road that fits and prove one harmless vertical slice first; the complete agent-executable doctrine is the packaged skill (skills/build-on-boombox/SKILL.md, installed into a consumer repo by boombox project init, served live as boombox://developer/skill).

|Shape|What it is|Author with|Prove locally, no mutation| |-|-|-|-| |Cassette|One capability as a governed, repeatable action: dry-run gated, typed outputs, every run receipted|CassetteSpecV2 YAML or defineCassette() (same grammar)|cassette_dry_run until the exact spec_hash is green| |Portable application|Your frontend + your live harness API in one immutable image, one origin, deployed and governed by Boombox|defineApplication / defineApplicationTarget / planBoomboxApplicationDeployment from @konstantdotcloud/boombox/apps|boombox_application_validate + boombox_application_plan| |Durable workload|A product-owned worker under Boombox admission, leases, fencing, checkpoints, and receipts|defineWorkload / defineWorkloadTarget / planBoomboxWorkload from @konstantdotcloud/boombox/workloads|boombox_workload_validate + boombox_workload_plan| |Optional subject-runtime primitive|A generic reducer that extends any selected Product shape with durable snapshots for independently addressed subjects|Packaged job/handle declarations plus @konstantdotcloud/boombox, /custody, and /job-io|Declaration dry-runs, the packaged local fixture, and custody conformance| |Existing capability|A library, CLI, legacy application, HTTP service, or MCP server exposed through its narrow qualified operation set|Existing capability/MCP registration plus explicit allowlist and immutable binding|Local adapter and refusal tests; arbitrary-endpoint qualification and automatic HTTP-to-MCP activation remain staged work|

All four Product shapes—and the optional primitive when selected—share one law: a green plan is not a deployment. Local validate/plan tools are deliberately non-authoritative; apply, publish, promote, trigger, and their receipts require the selected Product account's production authority. Where that authority is unavailable, the honest terminal result is the validated plan plus the exact missing adapter — never a fabricated deployment, run, or receipt. The deeper contracts for each shape are in the sections above and in the packaged skill.

Optional subject-runtime job loop

Choose this loop when the Product needs a generic reducer to maintain durable snapshots for independently addressed subjects. It extends the cassette, portable-application, durable-workload, and existing-capability roads; it does not replace them. Stateless and local applications remain first-class and skip this loop. The packaged fixture is a cloneable starting point, never a required Product, workflow, UI, model, or deployment shape.

Authority model

Boombox keeps three authorities separate:

• Observer authority reads job status, subject status, subject heads, head content, and run evidence.
• Product-account authority registers and changes jobs, subjects, handles, plans, credentials, and runs.
• An injected application operation credential provides a bounded read surface inside a deployed application.

Every connected job, subject, and handle verb sends its credential only to the enrolled Product runtime host. If no runtime host is enrolled, the CLI refuses before issuing a request and never falls back to the control gateway.

Never put credential values in command arguments, declarations, logs, prompts, fixtures, or reports. The CLI resolves observer and Product-account bindings from its selected configuration. Direct SDK composition supplies the two authorities separately and refuses when the same value is used for both.

The injected application client refuses every mutation before issuing a request with code APPLICATION_READ_ONLY and this remedy:

Use the product-account setup composition or a product-bound mutation path.

Supported job journey

The installed subject-runtime fixtures are under:

node_modules/@konstantdotcloud/boombox/fixtures/subject-runtime/

Copy job-declaration.json and handle.json into your repository, then edit their domain fields. Keep job.json, input.json, heads.json, and fixture-reducer.mjs together when running the packaged local example.

1. Validate declarations locally

./node_modules/.bin/boombox job register ./job-declaration.json --dry-run
./node_modules/.bin/boombox handle create ./handle.json --dry-run

A valid dry run exits 0 without loading a connection or issuing a request. An invalid declaration exits 1 and prints the first failing field plus a remedy.

The accepted job declaration has this shape:

{
  "tenant_id": "tenant_fixture",
  "subject_kind": "fixture_snapshot",
  "environment": "staging",
  "versions": [
    {
      "job_version": 1,
      "reducer": {
        "image_ref": "oci://registry.example/fixture/reducer@sha256:1111111111111111111111111111111111111111111111111111111111111111",
        "image_digest": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
        "command": ["node", "./fixture-reducer.mjs"],
        "env_allowlist": []
      },
      "snapshot_schema_ref": "bb://schemas/fixture-snapshot/v1",
      "handles": []
    }
  ],
  "active_version": 1,
  "due": {
    "compose": "any",
    "rules": [{ "kind": "every", "seconds": 3600 }],
    "scheduler": "external_scheduler"
  },
  "dependencies": [],
  "requeue_max_depth": 3,
  "timeout_ms": 5000,
  "placement": {
    "lane": "bl_ffffffffffffffffffffffffffffffff",
    "project": "fixture-project",
    "region": "local",
    "residency_class": "local"
  }
}

Hosted operations have three additional requirements: reducer.image_ref must itself include the exact @sha256:… suffix even when image_digest is present; job promote requires the selected version's qualification { qualification_ref, qualification_digest } (staging accepts the reducer image digest); and job trigger --now applies to watched source events, so a handle-less job refuses with JOB_TRIGGER_NO_EVENT, an external_scheduler job refuses with JOB_TRIGGER_EXTERNAL_SCHEDULER, and a host_tick every rule admits due runs automatically after a subject is bound.

The accepted handle declaration has transport, location, format, schema digests, ontology mapping, identity and time policies, freshness, budget, event identity, rights references, resource owner, region, and residency class. Use the complete installed handle.json fixture as the starting document.

2. Prove the registered job locally

Run the complete installed job.json unchanged:

PKG_ROOT=node_modules/@konstantdotcloud/boombox
./node_modules/.bin/boombox job run-local \
  "$PKG_ROOT/fixtures/subject-runtime/job.json" \
  --input "$PKG_ROOT/fixtures/subject-runtime/input.json" \
  --heads "$PKG_ROOT/fixtures/subject-runtime/heads.json" \
  --mode files \
  --store memory

--mode open-commit proves the same reducer through the service-run open/commit boundary. --store dir <path> persists content, pointers, and durable head metadata under the supplied directory; the positional <path> follows job.json:

./node_modules/.bin/boombox job run-local \
  "$PKG_ROOT/fixtures/subject-runtime/job.json" ./job-store \
  --input "$PKG_ROOT/fixtures/subject-runtime/input.json" \
  --mode open-commit \
  --store dir

The local host validates the shared job input/output schemas, mounts the generated handle grant file read-only for Docker reducers, commits snapshots through the custody port, and records a durable head-to-metadata link. It does not rewrite the registered job.json.

The hosted reducer contract is the same file contract proven by job run-local: the host materializes one immutable boombox.job-input/v1 document at launch, supplies its path and the reducer output path through BOOMBOX_JOB_INPUT and BOOMBOX_JOB_OUTPUT, validates the canonical job-output schema, and publishes boombox.job-output/v1 plus snapshots with derived content_type. A hosted run requires a host granted workload_runtime and an approved active workload revision; admission remains typed, including WORKLOAD_TARGET_NOT_APPROVED, WORKLOAD_RUNNER_UNSUPPORTED, WORKLOAD_IMAGE_NOT_APPROVED, and WORKLOAD_REVISION_NOT_ACTIVE. Treat the local run as reducer-contract proof, not proof of a live hosted run.

3. Register and connect

Use an authorized Product-account binding for connected mutations:

./node_modules/.bin/boombox job register ./job-declaration.json
./node_modules/.bin/boombox handle create ./handle.json
./node_modules/.bin/boombox handle connect <handle> <job>
./node_modules/.bin/boombox subject register ./subject.json

Every connected refusal carries both its message and remedy. A registration or connection may return created or reused; both are successful, idempotent outcomes.

4. Inspect status, heads, content, and evidence

Observer commands read current state:

./node_modules/.bin/boombox job status <job>
./node_modules/.bin/boombox subject status <subject>
./node_modules/.bin/boombox subject heads <subject> --environment staging

The SDK adds validated head content and run evidence reads:

import { createBoomboxSubjectRuntimeClient } from '@konstantdotcloud/boombox';

const client = createBoomboxSubjectRuntimeClient({
  base_url: gateway_origin,
  observer_credential: observer_authority,
  product_account_credential: product_account_authority,
});

const registration = await client.ensureSubject({
  kind: 'fixture_snapshot',
  external_key: 'fixture-subject',
  entity_refs: [],
  job_ids: [],
});

const { heads } = await client.listSubjectHeads(registration.subject_id, 'staging');
if (heads[0]) {
  const content = await client.readHeadContent(heads[0]);
  const evidence = await client.getRunEvidence(heads[0].run_id);
  console.log(content.digest, content.content_type, content.size_bytes, evidence.ref);
}

ensureSubject() and its alias registerSubject() return { status: 'created' | 'reused', subject_id, subject }. listSubjectHeads() returns validated heads plus a nullable cursor. Each head includes content_type and nullable run_receipt.

readHeadContent() sends x-boombox-expected-digest, requires the response ETag and x-boombox-content-digest to match the head, verifies the SHA-256 bytes, and limits the response to 25 MiB by default. Supply { max_bytes } for a smaller bound. Transport, refusal, and integrity failures use BoomboxContentTransportError, BoomboxContentRefusal, and BoomboxContentIntegrityError.

getRunEvidence() returns { run_id, ref, digest, media_type }. Non-terminal, missing-receipt, and mismatch refusals preserve the gateway code, message, and remedy in BoomboxRunEvidenceRefusal.

Injected application reads

resolveBoomboxAppRuntime() synchronously validates the required runtime environment. The operation credential is loaded lazily from the file named by BOOMBOX_APP_OPERATION_TOKEN_FILE; tests and embedders may provide the read_file dependency.

Each data_handles[] entry may declare env: { bucket?, prefix?, uri? } with application-owned uppercase environment names; Boombox delivers the admitted values under those names and reports the wiring through data_handles(), while runtime identity—not any delivered value—remains the credential.

import {
  createInjectedSubjectRuntimeClient,
  resolveBoomboxAppRuntime,
} from '@konstantdotcloud/boombox/apps';

const runtime = resolveBoomboxAppRuntime();
if (runtime.status === 'injected') {
  const client = createInjectedSubjectRuntimeClient(runtime);
  const status = await client.getSubjectStatus(subject_id);
  const { heads } = await client.listSubjectHeads(subject_id);
  const content = heads[0] ? await client.readHeadContent(heads[0]) : null;
  const evidence = heads[0] ? await client.getRunEvidence(heads[0].run_id) : null;
  console.log(status, content?.digest, evidence?.ref);
}

The injected client supports getSubjectStatus, listSubjectHeads, getJobStatus, readHeadContent, and getRunEvidence. It does not derive authority from any other environment value or read any other file.

Custody conformance

The default in-memory custody store is fail-closed for destructive authority. Its documented conformance one-liner returns a report:

import {
  createMemoryBoomboxContentCustody,
  runBoomboxContentCustodyConformance,
} from '@konstantdotcloud/boombox/custody';

const report = await runBoomboxContentCustod