diff --git a/docs/architecture/COMPONENT_MANIFEST_CONTRACT.md b/docs/architecture/COMPONENT_MANIFEST_CONTRACT.md index c0a34d5..bbf3977 100644 --- a/docs/architecture/COMPONENT_MANIFEST_CONTRACT.md +++ b/docs/architecture/COMPONENT_MANIFEST_CONTRACT.md @@ -1,16 +1,54 @@ # Component-manifest contract -A future Forge Platform component manifest declares a tested release composition without embedding production endpoint choices in source control. +A Forge Platform component manifest declares a tested release composition of independently published product artifacts. It does not build producer artifacts, infer them from source checkouts, or embed production endpoint choices in source control. -For each platform release and component, it must identify: +## Evidence-gated manifest finalization + +A final manifest entry may be created only after the producing product has published the installable artifact and exposed the evidence required to identify and qualify those exact bytes. + +A source merge or Git SHA alone is not an installable artifact. The manifest pins the artifact digest and separately records source provenance. + +For each platform release and component, the manifest must identify at least: - Forge Platform release version; - component identity and version; -- artifact URI or source reference; -- artifact digest; -- signature and provenance evidence; +- source repository/revision provenance; +- artifact URI/name or qualified acquisition reference; +- artifact digest, normally SHA-256 over the installable bytes; +- signature and provenance evidence where supported; +- qualification/release evidence reference; - supported operating systems and architectures; - protocol compatibility; and -- required and optional dependencies. +- required and optional component dependencies. + +Credentials are never embedded in the manifest. Artifact acquisition resolves credentials through the qualified installation/release boundary. + +## Cross-repository dependency boundary + +Forge owns engineering planning and may model a hard dependency from a Forge Platform Action to a producer Action. Forge Platform owns only the composition artifact that results. + +Example: + +```text +EP-A5 publish qualified EP Server + Project Agent artifacts + output evidence: + server wheel identity + SHA-256 + source revision + agent wheel identity + SHA-256 + source revision + qualification/provenance refs + +FP-A2 implement Agent installer role + may proceed independently while EP product work continues + +FP-A3 finalize component manifest + depends_on = [EP-A5, FP-A2] +``` + +`FP-A3` must not be considered complete until the exact published producer artifacts exist. This permits useful parallel implementation without allowing the composition manifest to guess future versions, Git revisions or checksums. + +The same rule applies to Forge Server, Workspace Server, Workspace Client, Engineering Platform Server and Engineering Platform Project Agent artifacts. + +## Manifest versus engineering Action graph + +The component manifest records a qualified release composition. It is not Forge's Living Mission Graph and does not carry the engineering execution DAG that produced the release. Action dependency and replanning authority remain Forge-owned; execution/admission evidence remains EP-owned. -The accompanying [JSON Schema](../../schemas/component-manifest.schema.json) is a structural contract, not a production manifest. Artifact locations and credentials are resolved only by future qualified release processes. +The accompanying [JSON Schema](../../schemas/component-manifest.schema.json) is a structural contract, not a production manifest. It must preserve the distinction between source revision and artifact identity/digest. diff --git a/docs/architecture/EVIDENCE_GATED_COMPONENT_COMPOSITION.md b/docs/architecture/EVIDENCE_GATED_COMPONENT_COMPOSITION.md new file mode 100644 index 0000000..3066e86 --- /dev/null +++ b/docs/architecture/EVIDENCE_GATED_COMPONENT_COMPOSITION.md @@ -0,0 +1,102 @@ +# Evidence-gated cross-repository component composition + +**Status:** target Forge Platform architecture; canonical when merged. Implementation and qualification remain separately governed. + +## Purpose + +Forge Platform owns installation and release composition of independently published Forge, Workspace and Engineering Platform artifacts. It must support a development flow where installer-role implementation can advance in parallel with producer work, while final release composition waits for exact published artifact evidence. + +This document defines that boundary for cross-repository Forge Missions. Forge owns the engineering Action graph; EP owns execution/admission/evidence; Forge Platform owns the final component manifest and installer behavior. + +## Parallel implementation versus final composition + +A producer artifact and its installer support do not need to be implemented serially. + +Example Mission: **make Engineering Platform Project Agents production-ready and installable**. + +```text +engineering-platform repository + EP-A1 contract + |\ + | +--> EP-A2 Agent runtime -------------------+ + +----> EP-A3 Server/Agent protocol -----------+--> EP-A4 package/qualify + | + v + EP-A5 publish artifacts + +forge-platform repository + FP-A1 Agent role/model --> FP-A2 installer support --------+ + | +EP-A5 published artifact evidence --------------------------+--> FP-A3 final component manifest + | + v + FP-A4 installer qualification +``` + +EP implementation and Forge Platform installer support may proceed concurrently when Forge declares them independent and EP execution resources permit it. + +The final component manifest is different: it is evidence-gated by the actual producer publication. + +## Producer evidence required for manifest finalization + +For each installable component, a final manifest entry must bind the installable bytes to source and qualification evidence. At minimum: + +```text +component identity +component version +source repository/revision +artifact name/acquisition reference +artifact SHA-256 or qualified digest +signature/provenance reference where available +qualification/release evidence reference +supported OS/architecture +protocol compatibility +component dependencies +``` + +The artifact digest identifies what will actually be installed. The source revision identifies where those bytes came from. Neither substitutes for the other. + +A future or guessed version/checksum is invalid. A source merge without the required published artifact is not enough to finalize the manifest. + +## Forge dependency edge + +Forge may materialize the final manifest Action with a hard dependency on the producer publication Action: + +```text +FP-A3.finalize_manifest.depends_on = [EP-A5.publish_artifacts, FP-A2.installer_support] +``` + +The `EP-A5` Action DoD should expose the artifact evidence needed by `FP-A3`. EP terminal evidence makes that producer outcome verifiable. Forge reconciles the evidence and only then releases the dependent Forge Platform Action. + +Forge Platform itself does not read Forge's planning database or EP CENTRAL directly. It consumes the qualified artifact references and produces its own repository change under ordinary EP execution. + +## Five first-class installable artifacts + +The same evidence-gated rule applies independently to: + +- Forge Runtime / Forge Server artifact; +- Workspace Server artifact; +- Workspace Client artifact; +- Engineering Platform Server artifact; +- Engineering Platform Project Agent artifact. + +A platform release can therefore be composed only when every required component in that release has its own published artifact evidence and the declared compatibility set has been qualified. + +## Dynamic replanning + +The component manifest is not an engineering plan. If producer evidence changes the work needed—for example, a protocol version changes or a new Agent packaging constraint appears—Forge may revise future Engineering Actions in the Living Mission Graph. The already published producer artifacts and already materialized Actions remain immutable evidence/history. + +## Qualification + +Qualification must prove: + +- installer-role implementation can proceed before producer artifact publication when no hard dependency exists; +- final manifest Action stays blocked before required producer artifact evidence exists; +- source merge alone cannot satisfy an artifact dependency; +- wrong artifact digest/source revision/provenance does not unlock the dependent Action; +- correct artifact evidence unlocks the dependent Action through Forge replanning/reconciliation; +- manifest schema keeps source revision distinct from artifact digest; +- every required manifest component references a qualified artifact rather than a mutable checkout; +- installer qualification uses the exact manifest-pinned artifact bytes. + +This is a natural cross-repository dogfood target after the first serial Forge dynamic-Mission canary and after EP qualifies the multi-execution/repository-lease/capacity capabilities needed for safe parallel work. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index c0d4b65..c1968cd 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -18,10 +18,20 @@ Components remain separately owned products even when installed on one machine. ## Execution-lane boundary -Forge plans dependency DAGs; Engineering Platform Server remains the durable execution and admission authority. After `STANDALONE_EP_VERIFIED`, its first parallelism capability is bounded mutation across different repositories: an Agent may serve `0..N` repositories and advertise bounded capacity, while EP enforces one mutating lock/lease holder per repository, admission, backpressure, fairness, evidence, and finalization. Workspace only presents or issues permitted control intent. See the [system architecture](FORGE_PLATFORM_ARCHITECTURE.md), [ownership matrix](OWNERSHIP_MATRIX.md), and [MVP roadmap](../roadmap/MVP_1_0.md). +Forge plans dependency DAGs; Engineering Platform Server remains the durable execution and admission authority. After `STANDALONE_EP_VERIFIED`, its first parallelism capability is bounded mutation across different repositories: an Agent may serve `0..N` repositories and advertise bounded capacity, while EP enforces repository/resource exclusion, admission, backpressure, evidence, and finalization. Workspace only presents or issues permitted control intent. + +Forge-owned hard dependency edges and EP-owned execution-resource constraints are separate. A Forge Platform Action may therefore be logically independent and eligible while EP still delays it for capacity, or it may remain logically blocked by producer evidence even when EP has free capacity. + +See the [system architecture](FORGE_PLATFORM_ARCHITECTURE.md), [ownership matrix](OWNERSHIP_MATRIX.md), and [MVP roadmap](../roadmap/MVP_1_0.md). + +## Evidence-gated release composition + +Installer/component support may be implemented in parallel with producer work, but final component-manifest entries require actual published artifact evidence. A source merge or guessed checksum is not enough. + +The canonical target is defined in [Evidence-gated cross-repository component composition](EVIDENCE_GATED_COMPONENT_COMPOSITION.md) and the [component-manifest contract](COMPONENT_MANIFEST_CONTRACT.md). Manifest entries keep source revision distinct from the digest of the installable artifact bytes. ## Lifecycle boundary The future platform manages install, role add/remove, upgrade, repair, uninstall, health diagnostics, and deployment receipts. Privileged installer logic is intentionally not implemented in this foundation. -Read the [system architecture](FORGE_PLATFORM_ARCHITECTURE.md), [governed knowledge learning loop](KNOWLEDGE_LEARNING_LOOP.md), [ADRs](adr/README.md), [cross-repository ownership matrix](OWNERSHIP_MATRIX.md), [component-manifest contract](COMPONENT_MANIFEST_CONTRACT.md), [compatibility model](COMPATIBILITY.md), [roles and presets](ROLES_AND_PRESETS.md), and [security boundary](SECURITY.md). +Read the [system architecture](FORGE_PLATFORM_ARCHITECTURE.md), [evidence-gated composition contract](EVIDENCE_GATED_COMPONENT_COMPOSITION.md), [governed knowledge learning loop](KNOWLEDGE_LEARNING_LOOP.md), [ADRs](adr/README.md), [cross-repository ownership matrix](OWNERSHIP_MATRIX.md), [component-manifest contract](COMPONENT_MANIFEST_CONTRACT.md), [compatibility model](COMPATIBILITY.md), [roles and presets](ROLES_AND_PRESETS.md), and [security boundary](SECURITY.md). diff --git a/docs/roadmap/README.md b/docs/roadmap/README.md index cdc20b9..efaf5c2 100644 --- a/docs/roadmap/README.md +++ b/docs/roadmap/README.md @@ -7,6 +7,7 @@ This directory is the canonical roadmap location for Forge Platform's cross-prod - [Forge Platform MVP 1.0](MVP_1_0.md) — product boundary, capability waves, a two-chain DAG that joins only at `MVP_1_0_RELEASE_READY`, the B8 → B8C → B8D → B9 → `STANDALONE_EP_VERIFIED` → `EP_EXTRACTION_CUTOVER_COMPLETE` transition gates, and separate post-verification lanes (CENTRAL relocation, EP self-hosting, and bounded multi-repository parallel execution). - [Policy-aware composition](POLICY_GOVERNANCE_V1.md) — scoped policy/release DAG for `POLICY_GOVERNANCE_AND_EFFECTIVE_PROFILES_V1`; native Forge release planning, EP enforcement and actual published artifact evidence precede qualified production installer composition. Documentation only; implementation remains PLANNED. - [Historical migration register](MIGRATION_REGISTER.md) — auditable classification of relevant historical DJConnect material and its canonical destination or retained status. +- [Evidence-gated component composition](../architecture/EVIDENCE_GATED_COMPONENT_COMPOSITION.md) — cross-repository sequencing seam: producer and installer implementation may proceed in parallel, while final component-manifest Actions wait for exact published artifact digest/source/qualification evidence. The earlier stage view is retained here as orientation only; it is superseded for MVP planning by the dependency-aware capability map in [MVP 1.0](MVP_1_0.md). @@ -26,6 +27,8 @@ a new first-canary dependency; production compositions require their real proof. The first post-verification parallelism capability is not general fleet scheduling: it is EP-owned, capacity-bounded mutation across independent repositories, with one mutating lane per repository. It starts only after `STANDALONE_EP_VERIFIED`; same-repository worktree/disjoint-scope parallelism remains a separate later capability. +Within that lane Forge may make independent producer and Forge Platform installer Actions concurrently eligible. Forge Platform's final release-composition/manifest work remains evidence-gated: a source merge is not a substitute for the exact published artifact bytes, digest, source revision and required qualification/provenance evidence. + ## Knowledge learning-loop integration Knowledge integration is additive and remains independently owned by `pcvantol/ai-platform-engineering-knowledge-base`. diff --git a/schemas/component-manifest.schema.json b/schemas/component-manifest.schema.json index 9ee2b5b..067f249 100644 --- a/schemas/component-manifest.schema.json +++ b/schemas/component-manifest.schema.json @@ -13,14 +13,44 @@ "component": { "type": "object", "additionalProperties": false, - "required": ["identity", "version", "artifact", "platforms", "protocol_compatibility", "dependencies"], + "required": ["identity", "version", "source_revision", "artifact", "platforms", "protocol_compatibility", "dependencies"], "properties": { "identity": {"enum": ["forge-runtime", "workspace-server", "workspace-client", "engineering-platform-server", "engineering-platform-project-agent"]}, "version": {"type": "string", "minLength": 1}, - "artifact": {"type": "object", "additionalProperties": false, "required": ["source", "digest"], "properties": {"source": {"type": "string", "minLength": 1}, "digest": {"type": "string", "pattern": "^[A-Za-z0-9._:+=-]+$"}, "signature": {"type": "string"}, "provenance": {"type": "string"}}}, - "platforms": {"type": "array", "minItems": 1, "items": {"type": "object", "required": ["os", "architecture"], "properties": {"os": {"type": "string"}, "architecture": {"type": "string"}}, "additionalProperties": false}}, + "source_revision": {"type": "string", "minLength": 1}, + "artifact": { + "type": "object", + "additionalProperties": false, + "required": ["source", "digest", "qualification"], + "properties": { + "name": {"type": "string", "minLength": 1}, + "source": {"type": "string", "minLength": 1}, + "digest": {"type": "string", "pattern": "^[A-Za-z0-9._:+=-]+$"}, + "signature": {"type": "string"}, + "provenance": {"type": "string"}, + "qualification": {"type": "string", "minLength": 1} + } + }, + "platforms": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "required": ["os", "architecture"], + "properties": {"os": {"type": "string"}, "architecture": {"type": "string"}}, + "additionalProperties": false + } + }, "protocol_compatibility": {"type": "object", "additionalProperties": {"type": "string"}}, - "dependencies": {"type": "object", "required": ["required", "optional"], "properties": {"required": {"type": "array", "items": {"type": "string"}}, "optional": {"type": "array", "items": {"type": "string"}}}, "additionalProperties": false} + "dependencies": { + "type": "object", + "required": ["required", "optional"], + "properties": { + "required": {"type": "array", "items": {"type": "string"}}, + "optional": {"type": "array", "items": {"type": "string"}} + }, + "additionalProperties": false + } } } }