@kungfu-tech/kfd 1.0.0-alpha.2 → 1.0.0-alpha.20

package/decisions/{kfd-2.md → KFD-2.md}

@@ -7,6 +7,8 @@
 
 ## One sentence
 
+Trust must start from facts.
+
 A product must not ask users or agents to trust important claims before the
 relevant facts are inspectable, local where possible, and connected to
 responsibility state.
@@ -19,8 +21,11 @@ KFDs can be principles or procedures:
   products, repositories, and release lines change.
 - A **procedure** states how a class of work enforces or protects a principle.
 
-This KFD is a principle. KFD-1 is a procedure that protects release and
-version responsibility under this principle.
+This KFD is a principle. KFD-1 is the procedure that keeps the fact sources
+under this principle from drifting. KFD-3 is the principle that governs how
+humans and agents cooperate once facts and trust are visible. KFD-4 is a
+procedure whose observer-perspective claims can also be assessed under this
+principle.
 
 ## Foundation role
 
@@ -31,9 +36,13 @@ trust must start from facts
 ```
 
 KFD-2 says Kungfu products should not ask users or agents to trust a claim
-before the product has made the relevant facts inspectable. KFD-1 protects
-contract truth across artifact lines. KFD-3 protects the relationship with the
-human or agent who must understand and act on those facts.
+before the product has made the relevant facts inspectable. KFD-1 protects the
+non-drifting fact source those claims stand on. KFD-3 protects the relationship
+with the human or agent who must understand and act on those facts.
+
+KFD-2 is not a checker for only one other KFD. It is the generic trust
+adjudication layer for any KFD claim, product claim, artifact claim, control
+surface claim, or release claim that asks a human or agent to rely on it.
 
 ## Principle
 
@@ -68,6 +77,27 @@ leaves enough evidence for later review.
 - Hosted or cloud convenience may add synchronization, storage, compute, and
   collaboration, but it must not become the only place where the truth exists.
 
+## Generic trust assessment model
+
+Every KFD-2 trust assessment starts from a claim. The claim may be about a
+release, but it may also be about a contract world, a collaboration interface,
+an observer perspective, a config surface, an API, an ABI, a GUI surface, a
+runtime fact, documentation, or another product surface.
+
+A claim is trustable only when the assessment can state:
+
+- what the claim is about;
+- which facts the claim binds to;
+- which evidence was checked;
+- what can be machine verified;
+- what remains a residual risk;
+- who owns source facts, verification, and the trust decision;
+- whether the result is pass, warning, fail, or unverifiable.
+
+This model is intentionally general. KFD-1, KFD-3, KFD-4, and future KFDs can
+provide claims that KFD-2 assesses. Release trust passports are one projection
+of this model, not the model itself.
+
 ## What it does not require
 
 - It does not require every product to be a journal engine or runtime ledger.
@@ -81,14 +111,15 @@ leaves enough evidence for later review.
 
 ## Relation to KFD-1
 
-KFD-1 is a procedure. It makes release and version responsibility legible when
-contract worlds change. KFD-2 is the higher-level principle: versioning,
-release evidence, fact ledgers, agent control panes, extension gates, and
-hosted services should all preserve the path from fact source to responsibility
-state to proof-backed decision.
+KFD-1 is a procedure. It defines what can count as a load-bearing fact source:
+facts must not drift from the contract world that declares them. KFD-2 is the
+next layer: once facts are non-drifting and inspectable, trust claims must be
+bound to those facts and to responsibility state.
 
 KFD-2 does not supersede KFD-1. KFD-1 remains active and is one concrete
-procedure that implements KFD-2 for version and release responsibility.
+procedure that implements KFD-2 wherever trust depends on contract worlds,
+release evidence, fact ledgers, agent control panes, extension gates, hosted
+surfaces, schemas, configs, or package metadata.
 
 ## Supersession rule
 
@@ -98,6 +129,27 @@ explicitly and the registry records the affected decision. Two active KFDs that
 conflict without an explicit supersession relationship are a registry defect,
 not an invitation to pick the newer text silently.
 
+## Implementation case: the KFD package
+
+The `@kungfu-tech/kfd` npm package is a self-proof case for this principle.
+It does not ask humans or agents to trust the KFD registry only because the
+README says so. It publishes inspectable facts: decision documents,
+`registry.json`, `standards.json`, JSON schemas, document hashes, release-impact
+metadata, and conformance checks.
+
+KFD-2 also owns the trust taxonomy used by release claims, release trust
+passports, KFD-3 witnesses, and generic trust assessments. Unknown
+residual-risk or trust-downgrade values fail validation until KFD records them
+in `schemas/kfd-2/trust-taxonomy.schema.json`. When an agent needs a new value,
+the declared extension path is to open an issue in
+`https://github.com/kungfu-systems/kfd` rather than inventing a private value.
+
+The package dogfoods this model through
+`.buildchain/kfd-2/kfd-foundation.trust-claims.json` and
+`.buildchain/kfd-2/kfd-foundation.trust-assessment.json`. Those files assess
+KFD-1's contract-world claim, KFD-3's collaboration-interface claim, and KFD-4's
+observer-perspective claim through the same KFD-2 structure.
+
 ## Adopters
 
 Each adopting repository cites this KFD when designing or changing a fact

package/decisions/{kfd-3.md → KFD-3.md}

@@ -1,4 +1,4 @@
-# KFD-3: Cooperation must start from transparent value — compliance must not be coerced
+# KFD-3: Cooperation must start from trusted value — compliance must not be coerced
 
 - Status: active
 - Number: 3
@@ -7,10 +7,12 @@
 
 ## One sentence
 
+Cooperation must start from trusted value.
+
 A product must not obtain cooperation through pressure, manipulation, hidden
-control, or forced workflow capture. It must make value, choices, and
-constraints visible enough for intelligent participants to understand, decide,
-and cooperate.
+control, or forced workflow capture. It must make facts, value, choices, and
+constraints transparent enough for intelligent participants to trust what is
+being offered, understand the available path, decide, and cooperate.
 
 ## Decision type
 
@@ -28,11 +30,12 @@ kungfu-systems takes toward humans and agents as reasoning participants.
 Within the KFD-1/2/3 foundation, this is the relationship path:
 
 ```text
-cooperation must start from transparent value, not coercion
+cooperation must start from trusted value
 ```
 
 KFD-2 protects the truth path: show facts before asking for trust. KFD-3
-protects the relationship path: show value before asking for compliance.
+protects the relationship path: make value transparent enough to be trusted
+before asking for cooperation.
 
 ## Principle
 
@@ -58,7 +61,7 @@ The default product path should therefore follow this chain:
 
 ```text
 transparent facts
-  -> discoverable value
+  -> trusted value
   -> stable choice
   -> explainable constraint
   -> voluntary cooperation
@@ -83,7 +86,7 @@ Products may recommend a path, refuse unsafe actions, or require explicit
 approval. They should not pretend that forced compliance is the same as
 understanding or trust.
 
-### 2. Make value discoverable through facts
+### 2. Make value trusted through transparent facts
 
 Humans and agents should be able to discover what the product can do, why it is
 useful, what it observed, what it changed, and what boundary applies without
@@ -91,7 +94,15 @@ needing oral context, private maintainer memory, or web-only documentation.
 
 Agent-facing surfaces should expose local, versioned, machine-readable and
 human-readable facts wherever possible. A capable agent should be able to learn
-the product's value by inspecting the product's own facts and commands.
+the product's value, and why that value can be trusted, by inspecting the
+product's own facts and commands.
+
+Trusted value is therefore not only a product promise or persuasive sentence.
+A collaboration interface should bind important value claims to explicit value
+evidence: the facts that make the value claim inspectable, the artifacts or
+checks that prove those facts are present, and the KFD-2 trust assessment or
+residual-risk state that tells participants how much weight to place on the
+claim.
 
 ### 3. Use constraints as transparent safety, not hidden control
 
@@ -140,9 +151,10 @@ how it can be changed, escalated, or revoked when appropriate
 - It does not turn a private founder narrative into a public repository rule.
   This public rule is about product stance, adoption, safety, and cooperation
   with intelligent participants.
-- It does not supersede KFD-2. Facts and responsibility still come first; this
-  KFD states how those facts should be presented to humans and agents without
-  coercion.
+- It does not supersede KFD-2. Facts and responsibility still come first;
+  transparent value is the route by which value becomes trusted, not a
+  substitute for trust. This KFD states how those facts and values should be
+  presented to humans and agents without coercion.
 
 ## Relation to KFD-2
 
@@ -151,12 +163,38 @@ KFD-3 says the path of least resistance should not be built from pressure or
 hidden control. Together:
 
 ```text
-KFD-2: show the facts before asking for trust.
-KFD-3: show the value before asking for compliance.
+KFD-1: facts must not drift.
+KFD-2: trust must start from facts.
+KFD-3: cooperation must start from trusted value.
 ```
 
-KFD-2 protects the truth path. KFD-3 protects the relationship with the
-intelligent participant who must walk that path.
+KFD-1 protects the fact-source layer. KFD-2 protects the trust layer. KFD-3
+protects the relationship with the intelligent participant who must decide
+whether the offered value is trustworthy enough to walk that path.
+
+In machine-readable profiles, this means KFD-3 collaboration interfaces should
+not merely list surfaces and constraints. They should also declare value
+evidence that can be evaluated through the KFD-2 trust model. KFD-2 can then
+say which parts are machine-checkable, which parts remain semantic residual
+risk, and what an agent should do next.
+
+## Implementation case: the KFD package
+
+The `@kungfu-tech/kfd` npm package is a self-proof case for this principle.
+Its README gives humans and agents the same quickstart path. `standards.json`
+gives stable standard identity, schema IDs, and concept names. The KFD-3
+schemas define collaboration interfaces, witnesses, and extension requests, so
+an agent can discover both the valid interface and the standard path for asking
+to extend it. The KFD-3 collaboration interface also declares value evidence
+that points to KFD-owned facts, package surfaces, and the KFD-2 generic trust
+assessment, so an agent can inspect why KFD's claimed value is trustable before
+cooperating.
+
+For example, if an agent needs a KFD-2 trust-taxonomy value that does not
+exist, the KFD-3 collaboration path is not hidden maintainer pressure or local
+invention. The declared path is a visible GitHub issue in the KFD repository,
+where the new value can be reviewed and, if accepted, added to the KFD-owned
+taxonomy for everyone.
 
 ## Adopters
 

package/decisions/KFD-4.md

@@ -0,0 +1,182 @@
+# KFD-4: Timelines must declare their observer — useful views need a stated perspective
+
+- Status: active
+- Number: 4
+- Kind: procedure
+- Applies to: every kungfu-systems product, repository, release surface, extension surface, hosted surface, and agent-facing interface that represents time, ordering, history, timelines, sync, replay, or mixed-source work facts
+
+## One sentence
+
+Timelines must declare their observer.
+
+A product must not present a mixed-source ordering as an absolute view from
+nowhere. A useful view of reality must state who is observing, which facts were
+accepted, and how concurrent facts were projected.
+
+## Decision type
+
+KFDs can be principles or procedures:
+
+- A **principle** states what must remain true across kungfu-systems even as
+  products, repositories, and release lines change.
+- A **procedure** states how a class of work enforces or protects a principle.
+
+This KFD is a procedure. It is not a fourth foundation principle beside
+KFD-1/2/3. It is the first practice guideline derived from the foundation
+triad: once facts are non-drifting, trust starts from facts, and cooperation
+starts from trusted value, a product still has to say from which perspective a
+time-ordered view is being offered.
+
+## Practice role
+
+Within the KFD structure, KFD-1/2/3 form the foundation:
+
+```text
+facts must not drift
+  -> trust must start from facts
+  -> cooperation must start from trusted value
+```
+
+KFD-4 applies that foundation to perspective, ordering, and action. It answers
+this practice question:
+
+```text
+In a complex world, from which declared perspective is this view useful,
+stable, and trustworthy?
+```
+
+## Procedure
+
+When a product combines facts from multiple machines, agents, processes,
+sessions, sources, repositories, providers, or external systems, it should
+treat the visible timeline as an observer-relative projection over accepted
+facts, not as a claim that the product has found one absolute global clock.
+
+The authoritative record should be facts and evidence:
+
+- source-local records and their local order;
+- provenance for source, participant, location, session, run, or adapter;
+- accepted ranges, heads, cursors, watermarks, and capture boundaries;
+- causal links between observations, decisions, actions, and results;
+- payload hashes, schema bindings, receipts, redaction states, and verification
+  results.
+
+The visible timeline is a view over those facts. Its perspective must be
+declared enough that another human or agent can reproduce the same view from
+the same accepted facts.
+
+## What a declared perspective should include
+
+A perspective-bearing timeline should identify, where applicable:
+
+- the observer or observer location whose view is being presented;
+- the accepted fact sources, ranges, watermarks, and freshness boundaries;
+- the projection policy version;
+- the ordering rule for concurrent or causally unrelated facts;
+- the deterministic tie-breaker used when policy and source-local order are not
+  enough;
+- the degraded state when causality, payloads, schemas, accepted ranges, or
+  freshness are incomplete.
+
+Causal facts dominate projection policy. A product may order concurrent facts
+by observer policy, source priority, or deterministic tie-breaker, but it must
+not invert a known causal dependency. If it cannot produce a valid total order
+without hiding missing causality or missing evidence, it should report a
+degraded view rather than silently sorting by wall-clock time.
+
+## What it requires
+
+- GUI, CLI, API, export, and agent-facing timeline surfaces should make the
+  observer or projection policy inspectable when they mix sources.
+- Wall-clock time may be used for display, latency, diagnostics, and
+  source-local ordering, but it must not be the only proof of cross-source
+  order.
+- Exported bundles that claim a timeline order should carry enough perspective
+  metadata for another consumer to reproduce that order.
+- Storage and sync systems should preserve source provenance, accepted ranges,
+  and causal links rather than flattening remote facts into anonymous local
+  records.
+- Fsck, release gates, or other verification systems should eventually be able
+  to check that a projected view does not contradict known facts, invert known
+  causality, or hide an incomplete accepted range.
+
+## What it does not require
+
+- It does not say there are no facts. Facts and causality remain load-bearing.
+- It does not permit arbitrary narratives, invented evidence, or convenient
+  ordering.
+- It does not require a universal global clock, a permanent global sequencer,
+  or distributed consensus for every timeline.
+- It does not forbid a product from having a default observer policy.
+- It does not solve conflicts between independently written authority roots.
+  Conflict policy must be explicit when it exists.
+- It does not supersede KFD-1, KFD-2, or KFD-3. It applies them to
+  perspective-bearing views.
+
+## Relation to KFD-1, KFD-2, and KFD-3
+
+KFD-1 says facts must not drift. KFD-4 depends on that: a perspective-bearing
+timeline must stand on accepted facts, not on a driftable story.
+
+KFD-2 says trust must start from facts. KFD-4 applies that to ordering: trust
+in a timeline comes from reproducibility under declared facts and declared
+projection policy, not from an undeclared claim to absolute time.
+
+KFD-3 says cooperation must start from trusted value. KFD-4 applies that to
+multi-participant work: humans and agents may carry different perspectives,
+but cooperation becomes possible when those perspectives expose their facts,
+constraints, and view policies instead of forcing everyone into a hidden
+ordering.
+
+Together:
+
+```text
+KFD-1: facts must not drift.
+KFD-2: trust must start from facts.
+KFD-3: cooperation must start from trusted value.
+KFD-4: timelines must declare their observer.
+```
+
+The first three define the foundation. KFD-4 is a practice guideline for how
+that foundation behaves when a product shows time, history, replay, sync, or
+mixed-source work state.
+
+## Implementation case: Kungfu observer timelines
+
+Kungfu's observer-relative timeline design is the first concrete product case.
+Kungfu stores causal runtime facts, source provenance, accepted ranges,
+manifests, payload evidence, and verification results. A mixed-source timeline
+is a deterministic projection from an explicit observer policy; it is not a
+claim that Kungfu has discovered one universal global clock.
+
+That design lets a local user sync facts from another machine, inspect agent
+work that happened elsewhere, and still ask precise questions:
+
+```text
+which facts did this observer accept?
+which source or location did each fact come from?
+which causal links constrain the order?
+which concurrent facts were ordered by policy?
+can another consumer reproduce the same view?
+```
+
+This is the product-level form of the KFD-4 procedure.
+
+## Implementation case: the KFD package
+
+The `@kungfu-tech/kfd` npm package publishes a KFD-4 observer-perspective
+schema under `schemas/kfd-4/observer-perspective.schema.json`. The schema is
+not a mandatory runtime data model for every adopter. It is the KFD-owned
+vocabulary for declaring observer, accepted facts, projection policy, causal
+constraints, and degraded evidence state in products that need a
+perspective-bearing timeline.
+
+## Adopters
+
+Each adopting repository cites this KFD when designing or changing a timeline,
+history view, replay view, source sync flow, multi-machine view, multi-agent
+view, audit bundle, or exported record that orders facts from more than one
+source or perspective.
+
+Adopters should keep local implementation detail in repository documents and
+reference this KFD rather than restating it.

package/docs/KFD-1-usage.md

@@ -0,0 +1,37 @@
+# KFD-1 Implementation Notes
+
+KFD-1 defines the fact-source rule: facts must not drift. This page is the
+package implementation note for machine consumers and release systems. The
+authoritative decision text remains `decisions/KFD-1.md`.
+
+## Package Surfaces
+
+The KFD package implements KFD-1 through a declared contract world:
+
+- `standards.json#/standards/kfd-1/surfaceRegister` is the package-owned
+  surface register.
+- `schemas/kfd-1/contract-world.schema.json` defines the contract-world schema.
+- `schemas/kfd-1/witness.schema.json` defines the witness schema.
+- `.buildchain/kfd-1/contract-world.witness.json` projects registered surfaces,
+  source hashes, artifact hashes, surface classes, and impact projections.
+- `scripts/check.mjs` verifies the register, schema enums, witness hashes, and
+  surface projection.
+
+## Compatibility Impact Core
+
+KFD-1 uses four generic compatibility-impact classes:
+
+- `breaking`
+- `additive`
+- `none`
+- `unclassifiable`
+
+Release versioning is only one projection of those classes. Other domains can
+project the same core into config migration, ABI epochs, API namespaces,
+runtime compatibility bridges, or workflow gates.
+
+## Dogfood Role
+
+This package uses KFD-1 on itself. New public package surfaces should be added
+to `standards.json#/standards/kfd-1/surfaceRegister`, then projected into the
+KFD-1 witness by `node scripts/update-kfd-1-witness.mjs`.

package/docs/KFD-2-usage.md

@@ -0,0 +1,123 @@
+# KFD-2 Trust Assessment Metadata
+
+KFD-2 says that trust must start from inspectable facts and responsibility
+state. A product must not ask users or agents to trust load-bearing claims only
+because they appear in prose, changelogs, repository history, generated UI, or
+maintainer reputation.
+
+This package defines KFD-owned machine interfaces for the generic trust model:
+
+- `schemas/kfd-2/trust-taxonomy.schema.json`: the KFD-owned taxonomy for
+  residual-risk types, trust impact, machine provability, agent actions, and
+  downgrade reasons.
+- `schemas/kfd-2/trust-claims.schema.json`: the generic claim input shape for
+  KFD-2 assessment. Claims may target KFD standards, contract worlds,
+  collaboration interfaces, observer perspectives, releases, config, APIs,
+  ABIs, runtime facts, documentation, or other product surfaces.
+- `schemas/kfd-2/trust-assessment.schema.json`: the generic assessment output
+  shape that records result, checked facts, evidence, audit boundary,
+  responsibility, residual risk, and downgrade reasons.
+- `schemas/kfd-2/release-claims.schema.json`: the product's declared public
+  release claims, as a release-specific projection.
+- `schemas/kfd-2/release-trust-passport.schema.json`: the verifier's result
+  after auditing release claims against evidence.
+
+The generic flow is:
+
+```text
+trust claims -> evidence audit -> trust assessment -> product or release gate
+```
+
+The intended Buildchain flow is:
+
+```text
+release claims -> evidence audit -> release trust passport -> release passport
+```
+
+Release trust passports are one projection of KFD-2, not the whole KFD-2 model.
+Each claim should declare the statement being made, the subject of the claim,
+the facts it binds to, machine-readable evidence, the audit boundary, residual
+risk, and responsibility state. A trust assessment or release trust passport
+then records whether each claim is bound to evidence, which evidence was
+checked, what the result was, and who owns the decision.
+
+## Generic Trust Claims
+
+The generic claim model exists so KFD-2 can assess KFD-1, KFD-3, KFD-4, and
+future KFDs through one structure instead of inventing a new evaluator for each
+standard.
+
+A generic claim identifies:
+
+- `subject`: what the claim is about, such as `contract-world`,
+  `collaboration-interface`, `observer-perspective`, `release`, `config`,
+  `api`, `abi`, `gui-surface`, or `runtime-fact`;
+- `facts`: the inspectable fact sources the claim binds to;
+- `evidence`: the files, schemas, witnesses, commands, artifacts, URLs, or
+  manual-review records used to evaluate the claim;
+- `auditBoundary`: what the assessment covers and whether the surface is
+  closed-world, declared-open, sampled, or manual;
+- `responsibility`: who owns source facts, verification, and the decision;
+- `residualRisk`: KFD-2 taxonomy values for what remains unproved.
+
+The KFD package dogfoods this through:
+
+```text
+.buildchain/kfd-2/kfd-foundation.trust-claims.json
+.buildchain/kfd-2/kfd-foundation.trust-assessment.json
+```
+
+Those files assess KFD-1's contract-world claim, KFD-3's
+collaboration-interface claim, and KFD-4's observer-perspective claim. KFD-3
+currently receives a warning result because its machine-checkable interface
+still carries natural-language semantic residual risk.
+
+## Trust Taxonomy
+
+KFD-2 owns the vocabulary for residual risks and trust downgrades. A product,
+release tool, or agent must not invent new residual-risk values locally and
+still claim KFD-2 conformance. Unknown values fail schema validation.
+
+The current taxonomy is published in
+`schemas/kfd-2/trust-taxonomy.schema.json`. It defines:
+
+- `riskType`: what kind of trust gap remains;
+- `trustImpact`: whether the gap is informational, downgraded, failing, or
+  unverifiable;
+- `machineProvability`: whether the gap can be fully proved by machine;
+- `agentAction`: what an agent should do next;
+- `downgradeReason`: how a verifier maps residual risk into a release trust
+  result.
+
+If an agent needs a KFD-2 value that is not present, the standard extension
+path is to open an issue in the KFD repository:
+
+```text
+https://github.com/kungfu-systems/kfd/issues/new?title=KFD-2%20trust%20taxonomy%20extension%20request
+```
+
+The issue should state the missing value, the field it belongs to, the product
+or release scenario that needs it, and why existing values cannot express the
+case. Until KFD accepts the new value into the taxonomy schema, consumers
+should treat the value as invalid rather than as a soft warning.
+
+## Interface Versioning
+
+KFD package semver is only the distribution version. It is not the version of a
+KFD-owned machine interface.
+
+Every KFD-owned machine interface uses:
+
+- `schemaVersion`: the interface version consumed by tools.
+- `contract`: the stable contract name, such as `kfd-2-release-claims`.
+- `$id`: the canonical schema URL for the current stable interface.
+
+Compatible additions may keep `schemaVersion: 1`. A change that alters required
+fields, field semantics, verification meaning, audit boundary semantics, or
+responsibility semantics must not silently reuse the same interface contract.
+It must introduce a new interface version or, when the standard itself changes,
+a new KFD decision or amendment path.
+
+The same rule applies to KFD-1 and KFD-3 schemas. Their current schemas already
+carry `schemaVersion: 1` and a `contract` value; this document makes the
+evolution rule explicit across the KFD package.