@kungfu-tech/buildchain 4.1.3-alpha.1 → 4.1.3-alpha.3

package/architecture/decisions/0007-hosted-pipeline-controller.md

@@ -0,0 +1,106 @@
+---
+status: draft
+period: ongoing
+theme: minimal-consumer-pipeline
+doc_type: architecture-decision-record
+source_level: local-files
+confidence: medium
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-13
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-13
+  visible_context: Third-child Assignment, existing Warrant domain, GitHub adapter source and local fault tests.
+  invisible_context_boundary: Hosted integration and published consumer qualification have not yet completed.
+---
+
+# ADR 0007: Hosted pipeline history and provider effects
+
+The normal pipeline admits repository-owned channel PRs using policy read from
+the protected base. PR TOML supplies the product commands to the credentialless
+build job. It cannot grant itself a channel route or lower protected review
+requirements. Source commit, tree, configuration blob and bytes are verified;
+the PR and protected branch are read again before returning an observation.
+Webhook fields select readback work and do not authorize effects. Terminal-only
+events cannot start product execution. Internal journal ref pushes are ignored.
+
+The hosted writer refines ADR 0006's storage boundary. GitHub Discussion appends
+do not provide atomic expected-head updates, and workflow concurrency alone
+does not fence an in-flight append from an interrupted writer. The pipeline
+therefore admits the existing immutable attempt records through one Git-ref
+journal. Each update has exactly one observed parent and uses a non-force
+fast-forward update; competing children cannot both advance that parent.
+The writer reads committed bytes back, including after a lost HTTP response.
+Discussion is a readable projection of the admitted records. It is not a
+second authority, and the earlier Discussion reader and histories remain
+available. The hosted path does not claim that the library's injected
+Discussion lock provides cross-process exclusion.
+
+An attempt's source generation, phase order and terminal history retain their
+ADR 0006 identities. Recovery opens a successor after terminal reconciliation;
+it does not inherit successful phases or rewrite prior results. Duplicate
+event keys must retain the same meaning. Product commands execute through the
+existing consumer-shell session with a credential allowlist and private file
+command channels. A subprocess result is an observation; independent hosted
+completion, artifact and source qualification remain necessary for reuse.
+
+Cancellation retains its exact provider readback material and commits a pending
+attempt record before invoking the existing Warrant domain transaction. Queued
+cleanup selects its own candidate even when another candidate is active.
+Active cleanup requires the admitted run attempt and separate native/seal jobs
+to be terminal in fresh provider readbacks. Lease expiry alone cannot release
+the Warrant. The credentialed independent heartbeat and finalizer check attempt
+stop requests. The native job retains its credentialless boundary and must
+finish or reach its hosted timeout before ownership can transfer; the controller
+does not cancel an entire GitHub run that could have acquired a newer run
+attempt. Domain expected-old roots and active fences are derived
+internally from fresh queue state.
+
+The public normal entry accepts only `config-path`. Its jobs separate runtime
+selection, provider control, credentialless product commands, independent build
+readback and guarded native delivery. The internal delivery component transports
+the retained request; admission, qualification and landing reject changed request
+fields and a different provider run attempt. Candidate source roots include the
+business attempt, so a terminal candidate cannot block a later attempt of the
+same source. Scheduling uses an expected journal head and retains live executions
+when jobs have not yet appeared in the provider inventory.
+
+Attempt wake selects its runtime lock from the recorded source commit. A changed
+source generation opens a successor only after old-candidate cleanup, then wakes
+again if its source requires another runtime selection. Branch notifications wake
+existing intents without inventing historical releases. Every declared product
+platform runs on the standard hosted matrix; the independent native command uses
+one declared platform, while exact merge-group verification repeats the complete
+product matrix. No additional native platform coverage is inferred from that
+single native execution.
+
+The protected base supplies review policy. Fresh GitHub readback must enforce
+the declared independent approval count, Code Owners, merge queue and required
+checks. PR approvals bind the exact source commit. Release-channel PRs use that
+protected queue; their merged source enters the separate publication stage.
+Development settlement requires the exact source PR, protected ancestry,
+successful exact merge-group execution and retained integration proof before
+the Warrant state changes. Terminal notifications replay retained receipts if a
+successor wake was interrupted.
+
+If a cancellation write succeeds but its response is lost, the retained pending
+material must match the candidate's terminal evidence before its attempt
+projection is completed. An interrupted successor dispatch can be retried from
+the same terminal evidence without rewriting history. Receipt material uses
+the existing immutable recovery archive and verifies digest and size on read.
+Neither the archive nor a planned operation grants merge or publication rights.
+
+Local tests currently cover the journal's competing writers and response loss,
+corrupt bytes, stale events and source drift, protected-policy selection,
+credentialless subprocess exit failures, native stop fencing, exact provider
+worker readback, queued versus active cleanup, lost settlement responses and
+interrupted successor wake. Tests also exercise the public controller's build
+and delivery handoff, duplicate-event retention, same-source successor identity,
+runtime source selection, exact merged settlement response loss and readable
+Discussion projection. Public workflow wiring is implemented; hosted execution
+and published qualification have not been claimed from these local tests. Product release
+drivers, the public recovery interface, self publication and final minimal
+consumer qualification remain the responsibilities of subsequent children.

package/architecture/decisions/0008-pipeline-product-publication.md

@@ -0,0 +1,99 @@
+---
+status: draft
+period: 2026-09-13
+theme: minimal-consumer-product-publication
+doc_type: architecture-decision-record
+source_level: local-files
+confidence: medium
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-13
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-13
+  visible_context: Product contract, hosted pipeline, provider adapters and local failure-path tests.
+  invisible_context_boundary: No published entry qualification, production publication or external consumer adoption is established by this document.
+---
+
+# ADR 0008: Product publication stays inside the business attempt
+
+The normal pipeline reads the existing schema-2 TOML and derives every declared
+product/platform/artifact and publication target. npm packages, native archives
+and Paper PDFs use the same entry and product build/verify boundary. Consumers
+do not supply standard packaging, signing, publication or recovery commands.
+
+After exact protected integration, the internal product component reserves one
+provider execution in the existing attempt journal. Its repository concurrency
+group serializes publication effects. Product commands run on separate hosted
+jobs with read-only checkout credentials and a credential-filtered subprocess
+environment. Qualification independently reads every completed platform job,
+artifact coordinate, manifest and actual payload. Missing platforms, redirected
+npm provider configuration and conflicting bytes are rejected.
+
+The plan binds the protected merge source, the original channel PR source, the
+selected runtime commit/tree and the defining publisher workflow SHA separately.
+Stable version materialization changes only declared version fields in an
+isolated Git ref. Its actual commit/tree and original protected source remain in
+the Passport; this is not a tree-equivalence claim. The Rust release domain admits
+the exact canonical product `apply` job and retains QUALIFY/APPLY/SETTLE ownership.
+
+When a preceding floating channel already names a version overlay, a new overlay
+retains that exact observed commit as a second Git parent. Its first parent is
+the current protected source, and independent tree comparison still permits only
+the declared version-file changes. This explicit merge ancestry preserves the
+previous release while allowing a provider-enforced fast-forward of the channel.
+
+The signer attests the complete qualified-product manifest with a predicate that
+binds both product sources, runtime, publisher and provider execution. The
+publisher verifies the GitHub/Sigstore bundle independently with the actual
+defining workflow SHA and provider run source SHA. A custom predicate carries the
+distinct materialized product source. This keyless signature is not an
+Authenticode or macOS application signature. npm's automatic provenance is
+disabled for this sealed publication path because its default workflow source
+would describe the controller checkout as the product build source. The retained
+custom attestation is published with the qualification and Capsule documents.
+
+Sealed payloads and signing bundles are retained in the existing immutable
+material archive before publication. Each provider operation records its intent
+before effects and retains exact successful readback before moving on. npm uses
+the sealed tarball, ignores lifecycle scripts and requires the registry integrity
+to match. GitHub assets and exact tags are never replaced. A lost response is
+reconciled from current provider state; completed packages are not republished.
+The Release contains product assets requested by TOML, its Passport, qualification,
+Capsule aggregate, invocation and attestation bundle.
+
+Publication success does not finish the business attempt. Distribution moves the
+npm channel and the major Git channel, with exact prior readback and no forced
+Git update or npm version regression. Divergent Git channel history stops for
+source reconciliation. Alpha then prepares the next development version through
+an ordinary protected PR. Its original publication and receipts remain successful
+while that PR waits for review, queue integration or verification. Anchored
+projects wait for a protected change to their declared version authority; the
+pipeline does not invent an upstream anchor. Stable publication prepares the next
+patch at Alpha zero from the current protected development source. A late
+completion observes already advanced development through exact protected PR
+proof and cannot regress its version. Stable and Alpha retain their distinct
+transition identities and the original successful publication.
+
+Provider authorization is a one-time repository setup. Hosted npm trusted
+publishing is preferred; `BUILDCHAIN_NPM_TOKEN` is an optional publisher-only
+credential. Internal PR creation uses the repository's automation App
+(`BUILDCHAIN_APP_CLIENT_ID` variable and `BUILDCHAIN_APP_PRIVATE_KEY` secret), or
+`BUILDCHAIN_AUTOMATION_TOKEN`. It does not use `GITHUB_TOKEN` to create a PR whose
+ordinary checks would be suppressed. No such credential reaches product commands.
+Review and branch protections still apply to generated PRs.
+
+The local tests cover real npm packing, native archives and PDFs, source and
+version drift, independent provider inventory, signature-verifier rejection,
+immutable retention, lost provider responses and protected next-development
+waiting/settlement. Hosted publication and the published floating consumer entry
+require separate execution evidence; passing these tests alone does not qualify
+that distribution boundary.
+
+Restricted npm products require the configured package read credential for provider
+readback; anonymous 404 responses cannot qualify private-package absence. This
+credential is confined to the fixed npm registry and is not supplied to product
+commands. npm OIDC publication does not imply private-package read authority
+([npm trusted publishing](https://docs.npmjs.com/trusted-publishers/)).

package/architecture/decisions/0009-pipeline-version-preparation.md

@@ -0,0 +1,186 @@
+---
+status: draft
+period: 2026-09-13
+theme: minimal-consumer-version-preparation
+doc_type: architecture-decision-record
+source_level: local-files
+confidence: medium
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-13
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-13
+  visible_context: Consumer compiler, prepared self product contract, product execution, version materialization, provider adapters and local adversarial tests.
+  invisible_context_boundary: Local tests do not establish published entry qualification, hosted provider authorization or completed self migration.
+---
+
+# ADR 0009: Regenerate version data before qualifying the final product source
+
+Changing a package version can invalidate generated documents that embed that
+version or hashes of other documents. Both publication and next-development
+preparation must regenerate those declared documents before creating the final
+Git source. Leaving the old documents in place would fail the ordinary clean
+source build, or publish facts that disagree with the product version.
+
+The runtime retains an exact preparation in the current attempt. It binds the
+source and TOML, selected runtime, target version, parent plan, purpose and
+declared platforms. An internal component checks out that source on separate
+product runners, patches only declared primary version fields, and executes the
+existing product install/build/verify commands without publication credentials.
+No new consumer command or workflow input is needed.
+
+The product result contains every declared version document and derived file.
+The source guard compares all original tracked bytes, types, executable modes,
+HEAD and tree directly; index flags cannot hide modifications. Only declared
+material bytes may change. Primary documents must exactly equal the pure version
+field patch. Changed derived documents from different platforms must agree.
+The source TOML, managed runtime locks and workflow authority cannot be generated
+as version material. Paths are literal, regular UTF-8 files with bounded size;
+symlink and submodule sources are not qualified by this preparation implementation.
+
+The ordinary product build also compares every tracked file directly with its
+admitted Git blob before and after executing commands. Index flags, local clean
+filters and ignored executable-mode changes cannot make altered bytes qualify.
+Tracked symbolic links retain their exact target bytes; parent directories
+cannot become links. Source checkout transformations must preserve the admitted
+bytes (Buildchain declares LF checkout in `.gitattributes`); unresolved submodules
+are rejected. This strengthens both the initial version-preparation source check
+and ordinary build qualification without granting product commands credentials.
+
+Project Cut replay transfers generated source patches through private temporary
+files instead of buffering them as command metadata. Git still applies the exact
+binary patch to an isolated index and compares stable patch identity and changed
+paths against the source. This permits large committed action bundles without
+changing the source composition, family receipt, conflict rejection or metadata
+output bound. Temporary descriptors and files are closed on success and failure.
+
+A separate job checks the original published caller, exact reusable definitions,
+provider run and retry, every successful platform job, and immutable artifact
+digests before reading results. The retained preparation and actual source
+contract are checked again before the qualified material enters the journal.
+Git materialization verifies the resulting tree, exact document bytes and ref.
+The final product build then runs against that exact materialized source and is
+qualified and signed through the existing publication boundary.
+
+For next-development, the same preparation starts from the retained current
+protected development source. It creates an ordinary PR and preserves the
+completed publication while waiting for protected review and integration.
+Recovery can reuse retained material only for the same parent and runtime;
+conflicting qualified results fail closed. Published payloads and provider
+receipts remain immutable under the existing recovery contract.
+
+This adds actual product execution when derived version files are declared.
+The publication component calls one shared internal version component for its
+two purposes. Each component stays within the existing job, step and module
+budgets. Local tests cover real child processes and Git byte guards, artifact
+transport rejection, retained request admission, materialization and existing
+recovery regressions. Hosted platform and provider qualification remain separate
+delivery requirements.
+
+An npm artifact may declare `path = "."` to pack the product directory through
+the standard runtime packer with lifecycle hooks disabled. Optional artifact
+`filename` data preserves established download names. Names are single bounded
+filenames with the declared format, unique across the full publication plan,
+and independently verified against the packed file. These fields do not expose
+publication commands or provider control to the consumer.
+
+The prepared `.buildchain/minimal-consumer.toml` declares Buildchain's npm
+package and the three existing binary downloads using those ordinary product
+fields. It retains all seven primary version documents and three derived
+documents. The contract is inactive: the current callers still select
+`.buildchain/buildchain.toml`. Publishing this preparation does not activate a
+second publisher or prove the self migration. The protected transition must
+qualify the published entry and selected runtime, preserve the existing stable
+qualification gates, retire the old consumer callers with a single writer,
+and finally use the shared normal/recovery pair and canonical TOML path.
+
+Each declared native checkpoint platform retains a full candidate action build,
+site generation and repository check through ordinary product commands. Linux
+runs this with the npm product; macOS and Windows run it with their standalone
+product. The full check includes the product's checkpoint clean-process and
+recovery tests; a binary version/help smoke test alone cannot replace source
+qualification. Rust formatting, lint and WASM toolchain components are explicit
+install commands on each platform. Local configuration checks establish this
+wiring only; the protected hosted executions and any remaining container-specific
+qualification must still pass before retiring the existing verification caller.
+
+Site generation reads its KFD upstream declarations from the product-owned
+`architecture/product-upstreams.json`. The existing collector receives this
+data explicitly, so changing the consumer TOML to the minimal schema preserves
+the product's seven upstream evidence assets and their digests. The legacy
+configuration retains its declarations until the protected caller cutover;
+the new data contains no build, publication or recovery orchestration.
+
+The prepared contract also declares stable eligibility as a closed `stable`
+table: minimum publication interval and canary soak in seconds, literal product
+paths, a product impact document, and whether published-entry qualification is
+required. It carries no workflow names, provider commands or evidence selectors.
+The publication plan retains an independent copy under its immutable root.
+The self preparation preserves the existing 86,400-second interval and
+3,600-second soak. The shared stable evaluator now rejects impact from another
+candidate version and duplicate canary observations instead of selecting the
+last observation. These declarations and local checks do not activate the new
+publisher: independent provider collection and enforcement in the pipeline
+remain required before the protected self cutover.
+Stable preparation and application now collect source facts after verifying
+the authoritative attempt. The collector resolves the exact public Alpha tag,
+requires the same channel PR source and compiled contract, and verifies every
+declared version document. It reads product impact from a bounded regular Git
+blob in that exact tree, independently checking its bytes and version. Product
+differences include added, removed and mode-changed files from complete Git
+trees; a short comparison listing cannot silently hide product changes.
+
+Complete bounded release pagination identifies the previous published product
+and the most recent earlier stable publication, including backports for the
+cooldown. The comparison must match the plan's retained previous channel.
+Fresh tag, release and predecessor observations reject concurrent changes.
+Same-version recovery does not count its own completed publication as an older
+release. These facts carry their own root and the exact publication plan root.
+
+New publication plans declare evidence version 1 and publish their full plan
+alongside qualification, capsules, invocation, attestation and Passport. The
+plan root is already bound by the signed product predicate. Recovery of an older
+retained transaction preserves its original evidence inventory and provider
+receipts; it does not retroactively add a plan or replace public bytes.
+
+Stable product qualification reads those fixed evidence assets from the exact
+Alpha release, with complete bounded pagination, unique identities, byte digests
+and a second asset readback. It checks the original signature through the
+central publisher workflow and exact provider source, reconstructs the Passport
+and invocation, and requires every declared product/platform output. Original
+build jobs and the signing job must still match provider readback, including
+their attempt, source, publisher definition and completion times. Historical
+qualification is checked at its issue time; it does not renew that receipt or
+authorize the current Stable publisher. Successful product evidence also causes
+another source observation before the eligibility decision.
+
+Published-entry qualification independently inventories completed normal PR
+runs after the exact Alpha release. It verifies the generated thin caller,
+published entry definition, managed source lock and selected candidate runtime,
+then reads the original native Attempt and retained product-build receipt.
+The normal consumer commit can differ from the released runtime commit; its
+compiled product contract must be identical. Every declared platform and the
+exact recorder job must agree with fresh provider readback. A newer failed or
+unrecorded matching build blocks fallback to older successful evidence. Recovery
+runs, foreign entries and an old runtime behind a new entry do not qualify.
+
+When only the publication interval or canary soak remains unsatisfied, preparation
+retains the eligibility and a source-bound waiting receipt in the same Attempt.
+An internal job outside the repository publication lock waits at most fifteen
+minutes, checks native ownership every thirty seconds, and wakes the same normal
+entry. The next execution recollects qualification; the waiting receipt grants
+no publication authority. Publication checks again before provider effects and
+can return to this waiting path if new evidence moves the soak deadline.
+
+The timer stops if its retained receipt is superseded, the Attempt changes or
+the phase advances. A successor can claim the exact waiting native head while
+the old outer run finishes its wake job; the existing worker fence then rejects
+the old publisher. Missing qualification and non-time failures remain errors.
+Local tests exercise real native records with deterministic provider facts and
+an injected clock, including bounded waits and stale-worker races. They do not
+establish live published qualification or activate the prepared self contract.
+Alpha preparation remains available for the protected transition; the legacy
+stable publisher retains its existing policy until the protected self cutover.