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

package/architecture/decisions/0005-minimal-consumer-contract.md

@@ -0,0 +1,122 @@
+---
+status: draft
+period: ongoing
+theme: minimal-consumer-contract
+doc_type: architecture-decision-record
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-12
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-12
+  visible_context: Immutable seven-child Assignment and current Buildchain source and tests.
+  invisible_context_boundary: The new pipeline and recovery entries are not yet implemented or published.
+---
+
+# ADR 0005: The consumer owns product intent, Buildchain owns execution
+
+## Contract and rollout boundary
+
+Schema 2 is a closed TOML contract compiled by
+`packages/core/consumer/contract/plan.js`. The compiler receives bytes and has no
+filesystem, process or provider interface. It never runs a configured command.
+Unknown fields fail, including arbitrary request envelopes and publication
+commands. Build and verification commands remain product code, executed later
+in an isolated job with no delivery, signing or publication credentials.
+
+Consumers maintain `.buildchain/buildchain.toml` and two generated callers.
+The normal entry receives the platform event and an optional `config-path`.
+Recovery receives one exact `attempt` and an optional transient `runtime-ref`.
+`entries.js` owns both interfaces and product-independent caller bytes.
+No consumer assembles candidate, Warrant, fence, proof, nonce, run, transaction
+or Discussion selectors. An attempt is a Buildchain business identity, not a
+GitHub run ID, run-attempt number or Discussion number.
+
+This first slice defines and tests that contract. Its generated examples are
+qualification fixtures, not a claim that the new public entries already exist.
+The normal controller is delivered in child 3; recovery in child 5; Buildchain
+self migration and published alpha/stable qualification in child 6; old public
+surface retirement in child 7. Schema 1 is not translated by the new compiler.
+Existing consumers remain on the old implementation until the reviewed
+migration replaces their configuration and entry together. There is no final
+compatibility wrapper, hidden script, or product-specific entry.
+
+## Product plan
+
+Each product declares an ID, type (`npm`, `binary`, `paper`), exact supported
+platforms, optional install commands, build and verify commands, output
+artifacts and publication targets. Artifact IDs are unique and targets must
+cover exactly the declared output set. npm publishing is a typed npm target;
+archive and PDF publication use GitHub Release. Provider credentials are
+one-time setup, never TOML values or command arguments.
+
+Version files, strategy, legal channel PR routes and required independent
+review/merge queue are explicit. Existing dependency locks remain ordinary
+product source and are retained by initialization/migration. The internal
+executor must install dependencies under their lock and current supply-chain
+policy. TOML cannot weaken branch protection or substitute a local check for
+independent source, receipt or provider readback.
+
+## Events, identities and authority
+
+The normal event vocabulary covers PR lifecycle, review, merge group and push.
+Buildchain-owned `repository_dispatch` wake events are internal notifications;
+their payload is untrusted until the controller verifies its retained attempt
+and provider evidence. There is no manual JSON dispatch interface. Wake events
+never create authorization and duplicate or old events cannot authorize a new
+source. The controller owns deduplication, writer fencing and terminal wakeup.
+Consumer YAML contains no event routing logic or internal workflow names.
+
+The trusted `pull_request_target: closed` notification also covers closing a
+conflicted PR, for which GitHub does not run `pull_request`. This is a
+cancellation/settlement observation only and must never execute PR code.
+Merge-group removal is reconciled from PR dequeue and live queue readback;
+`merge_group` subscribes only to GitHub's supported `checks_requested` type.
+See the [GitHub event contract](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows).
+
+The platform-provided event is only an observation. Admission resolves the
+repository, PR head/base and tree through trusted provider readback. Config
+bytes bind to the exact Git blob, config path and source commit. The compiler
+returns data; its digest is not merge or publication authority. PR-controlled
+config and artifacts are not consumed in a job holding privileged credentials.
+Caller permission declarations are upper bounds; internal jobs must narrow
+them and keep untrusted builds separate from qualification and provider writes.
+Fork events must never receive repository write credentials or inherited secrets.
+
+The generated contract lock binds the contract version, entry SHA, selected
+runtime SHA and configuration byte digest. It does not bind the consuming Git
+commit: committing a tracked lock must not invalidate that same lock. Exact
+source commit/tree identity is bound separately for each execution attempt.
+Entry and runtime may differ. A normal run
+uses its admitted lock; recovery may select a repaired runtime once through
+the central entry. Downstream nodes do not compare Buildchain SHAs. A changed
+contract requires an explicit reviewed config/lock upgrade; schema mismatch
+fails rather than silently interpreting old data. An entry bug requires an
+upgraded published entry and a full new execution.
+
+## Evidence and enforcement
+
+`generate-minimal-consumer-contract.mjs --check` verifies all three generated
+examples and the complete migration inventory of current public/self inputs,
+caller edges, template/fixture configuration and consumer scripts. Inventory
+destinations distinguish provider setup, plan-derived internal arguments and
+attempt-owned material/authority. They are migration obligations, not deleted
+functionality or already-migrated state.
+
+`inspectConsumerContract` requires the exact two generated workflows and scans
+the supplied complete consumer tree for known internal orchestration. The
+caller comparison closes YAML wiring; the TOML validator closes configuration
+keys. Source scanning detects known bypasses but is not a proof of arbitrary
+program behavior. Credential isolation and provider authorization remain
+mandatory even when this static gate passes. Child 7 must validate the final
+reachable source/generator closure and adversarial cases after migration.
+
+Tests compile all three plans, reject invalid input/state/route/target/review
+changes, verify exact Git blob binding with different entry/runtime commits,
+and build actual package contents, a native archive and a valid PDF in isolated
+directories. These are local contract/product tests; they do not constitute
+hosted execution, release, provider authorization or recovery qualification.

package/architecture/decisions/0006-business-attempt-journal.md

@@ -0,0 +1,89 @@
+---
+status: draft
+period: ongoing
+theme: minimal-consumer-attempt-journal
+doc_type: architecture-decision-record
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-12
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-12
+  visible_context: Captured second-child Assignment, Discussion implementation and local fault tests.
+  invisible_context_boundary: Hosted pipeline integration and published consumer qualification belong to later slices.
+---
+
+# ADR 0006: One PR intent, immutable generations and recoverable attempts
+
+The internal `workflow/attempt` modules extend the existing Release Discussion
+journal. PR number, repository identity and target branch identify the intent.
+Exact source commit, tree, TOML blob/digest/path and observed protected base
+identify a generation. A request key plus generation and predecessor identifies
+a business attempt. Provider run, run-attempt and job identify each writer;
+several provider runs may contribute to one business attempt.
+
+The admitted ordered phase set covers admission, build, review, Warrant, merge,
+publication, distribution and next-development. A channel-specific plan may
+omit inapplicable phases. Every phase requires successful predecessors. Waiting,
+failure, cancellation and supersession retain a reason. Terminal phase results
+cannot be rewritten: recovery opens a successor with no inherited success.
+Published historical results remain readable even when a new source or base
+requires a new generation. Projection completion does not grant delivery,
+publication or material-reuse authority.
+
+Each event includes its content digest, previous event digest, exact attempt
+and generation, sequence, bounded idempotency key, writer and runtime reader
+identity. Replay rejects gaps, forks, conflicting duplicate keys, undeclared
+or out-of-order phases, missing predecessors, identity drift and history bounds.
+Identical repeated records have one meaning. A reader may receive pages out of
+order; sequence and content links reconstruct the original history.
+
+`businessAttemptStore` uses the existing provider-authenticated Discussion
+transport, immutable attempt roots and reply pagination. Only the expected
+writer's unedited records contribute. Initialization verifies the repository
+node identity. Unknown mutation responses are reconciled by reading back the
+same immutable identity before retry. No attempt state is written into the
+consumer source tree and no independent index or second authoritative store
+is introduced.
+
+The store has no default lock. Its internal `exclusive.run` adapter must own
+the repository/intent writer scope across hosted processes and retain that
+exclusion through the final provider mutation. `assertOwner` is rechecked at
+scope admission and immediately before create/append. Expected-head comparison
+and current-attempt checks fence stale results. The adapter must not transfer
+ownership while an in-flight provider mutation can still commit: a local mutex
+or a check followed by an unfenced lease expiry is insufficient. Child 3 owns
+the hosted controller adapter; this library slice does not claim hosted writer
+exclusion from the injected test fixture. The provider remains the persistence
+authority; a fork makes the reader fail closed rather than selecting a winner.
+
+Material references distinguish artifacts, checkpoints, receipts, Passports
+and provider readbacks. Each binds byte count, digest, producing attempt,
+generation and a permanent consumer-repository URL. Signed URLs and credentials
+are rejected. A reused material ID cannot acquire different bytes. The internal
+material verifier checks retrieved bytes; storing a reference alone does not
+prove retrieval, provider authorization or qualification for another attempt.
+Existing receipt, Passport and provider journal rules continue to own those
+facts. Recovery must qualify retained material under the successor's current
+rules before emitting fresh evidence.
+
+The retained `dist/readers/business-attempt.cjs` is self-contained and accepts
+captured authenticated JSON on stdin. Its CLI outputs status, reason, attempt,
+generation, missing phases and the one recovery selector. The bundle is
+reproducibility-checked alongside the historical release reader and tested in
+a fresh process with filesystem access restricted to the bundle. It has no
+provider write or effect-recovery entry. A runtime's recorded reader digest
+must be verified by the existing archive-loading boundary before execution;
+the pure reader does not authenticate caller-supplied records itself.
+
+The fault tests cover identity drift, incomplete and corrupted chains, duplicate
+and out-of-order delivery, concurrent/stale writers, cancellation/failure state,
+response loss after provider commit, restart, untrusted/edited records, material
+integrity and published-history preservation. Hosted control, user-facing
+attempt selection, actual provider recovery and self publication remain the
+explicit responsibilities of children 3 through 7. This slice adds no public
+workflow or consumer input.

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/)).