@cassiomc1/forgeloop 2.0.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/.cursor/rules/project-loop.mdc +1 -1
  2. package/.github/copilot-instructions.md +1 -1
  3. package/AGENTS.md +1 -1
  4. package/CLAUDE.md +1 -1
  5. package/ENG/design-code-eng.md +7 -5
  6. package/ENG/dotnet-aspnetcore-development-eng.md +8 -4
  7. package/ENG/nodejs-backend-development-eng.md +7 -4
  8. package/ENG/sql-development-eng.md +5 -4
  9. package/ENG/taste-frontend-eng.md +19 -5
  10. package/PROTOCOL_INTEGRATION.md +21 -0
  11. package/README.md +10 -7
  12. package/THIRD_PARTY_NOTICES.md +1 -0
  13. package/completions/_forgeloop +6 -1
  14. package/completions/forgeloop.bash +11 -1
  15. package/completions/forgeloop.fish +40 -1
  16. package/docs/AGENT_PROTOCOL_SUMMARY.md +6 -1
  17. package/docs/CLI_REFERENCE.md +88 -3
  18. package/docs/CODE_ATTESTATION.md +7 -0
  19. package/docs/FORGELOOP_AUDIT.md +1 -1
  20. package/docs/GETTING_STARTED.md +8 -1
  21. package/docs/PACKAGE_CONTENTS.md +4 -5
  22. package/docs/RELEASE_CHECKLIST.md +67 -13
  23. package/docs/STABLE_2_ACCEPTANCE.md +118 -71
  24. package/docs/TROUBLESHOOTING.md +167 -0
  25. package/package.json +1 -5
  26. package/src/cli.js +26 -0
  27. package/src/commands/assess.js +36 -0
  28. package/src/commands/evidence-export.js +17 -0
  29. package/src/commands/evidence-verify.js +36 -0
  30. package/src/commands/sync-pull.js +46 -0
  31. package/src/commands/sync-push.js +49 -0
  32. package/src/core/assessment/facts.js +146 -0
  33. package/src/core/assessment/plan.js +133 -0
  34. package/src/core/cli-command-definitions.js +70 -0
  35. package/src/core/command-executors.js +26 -3
  36. package/src/core/error-codes.js +232 -2
  37. package/src/core/evidence/bundle-format.js +72 -0
  38. package/src/core/evidence/export.js +179 -0
  39. package/src/core/evidence/markdown.js +40 -0
  40. package/src/core/evidence/verify.js +179 -0
  41. package/src/core/integration-invocation-policy.js +4 -2
  42. package/src/core/next-action-review-phase.js +14 -5
  43. package/src/core/parsers/dotnet-project.js +221 -0
  44. package/src/core/parsers/limits.js +9 -0
  45. package/src/core/parsers/pubspec.js +307 -0
  46. package/src/core/parsers/shared.js +4 -0
  47. package/src/core/project-detection.js +6 -527
  48. package/src/core/sync/remote.js +124 -0
  49. package/src/core/sync/snapshot.js +129 -0
@@ -11,6 +11,12 @@ import {
11
11
  E_VERIFICATION_ISOLATION_UNAVAILABLE,
12
12
  } from "./verification-execution.js";
13
13
 
14
+ export const E_SYNC_CONFIG = "E_SYNC_CONFIG";
15
+ export const E_SYNC_UNAUTHORIZED = "E_SYNC_UNAUTHORIZED";
16
+ export const E_SYNC_CONFLICT = "E_SYNC_CONFLICT";
17
+ export const E_SYNC_REMOTE = "E_SYNC_REMOTE";
18
+ export const E_SYNC_SNAPSHOT_INVALID = "E_SYNC_SNAPSHOT_INVALID";
19
+ export const E_SYNC_TOO_LARGE = "E_SYNC_TOO_LARGE";
14
20
  export const E_REPOSITORY_INDEX_PLATFORM_UNSUPPORTED = "E_REPOSITORY_INDEX_PLATFORM_UNSUPPORTED";
15
21
  export const E_REPOSITORY_INDEX_ENGINE_MISSING = "E_REPOSITORY_INDEX_ENGINE_MISSING";
16
22
  export const E_REPOSITORY_INDEX_ENGINE_DOWNLOAD_FAILED = "E_REPOSITORY_INDEX_ENGINE_DOWNLOAD_FAILED";
@@ -89,6 +95,8 @@ export const E_ATTESTATION_MANIFEST_STALE = "E_ATTESTATION_MANIFEST_STALE";
89
95
  export const E_ATTESTATION_CONTENT_MISMATCH = "E_ATTESTATION_CONTENT_MISMATCH";
90
96
  export const E_ATTESTATION_SCOPE_MISMATCH = "E_ATTESTATION_SCOPE_MISMATCH";
91
97
  export const E_ATTESTATION_COVERAGE_GAP = "E_ATTESTATION_COVERAGE_GAP";
98
+ export const E_EVIDENCE_BUNDLE_INVALID = "E_EVIDENCE_BUNDLE_INVALID";
99
+ export const E_EVIDENCE_EXPORT_UNAVAILABLE = "E_EVIDENCE_EXPORT_UNAVAILABLE";
92
100
  export const E_ATTESTATION_COVERAGE_CONFLICT = "E_ATTESTATION_COVERAGE_CONFLICT";
93
101
  export const E_ATTESTATION_STATEMENT_MISSING = "E_ATTESTATION_STATEMENT_MISSING";
94
102
  export const E_ATTESTATION_STATEMENT_INVALID = "E_ATTESTATION_STATEMENT_INVALID";
@@ -241,6 +249,8 @@ const EXTENSION_PUBLIC_ERROR_CODES = Object.freeze(Object.fromEntries([
241
249
  E_ATTESTATION_CONTENT_MISMATCH,
242
250
  E_ATTESTATION_SCOPE_MISMATCH,
243
251
  E_ATTESTATION_COVERAGE_GAP,
252
+ E_EVIDENCE_BUNDLE_INVALID,
253
+ E_EVIDENCE_EXPORT_UNAVAILABLE,
244
254
  E_ATTESTATION_COVERAGE_CONFLICT,
245
255
  E_ATTESTATION_STATEMENT_MISSING,
246
256
  E_ATTESTATION_STATEMENT_INVALID,
@@ -663,6 +673,39 @@ const REPOSITORY_INDEX_ERROR_METADATA = Object.freeze(Object.fromEntries([
663
673
  safeResolution,
664
674
  })])));
665
675
 
676
+ const CLOUD_SYNC_ERROR_METADATA = Object.freeze(Object.fromEntries([
677
+ [E_SYNC_CONFIG, [
678
+ "Cloud sync is missing FORGELOOP_SYNC_TOKEN or a FORGELOOP_SYNC_KEY of at least 16 characters, or --remote or --repo is invalid.",
679
+ "Set both environment variables and pass an https --remote and an owner/name --repo, or a GitHub git origin.",
680
+ ]],
681
+ [E_SYNC_UNAUTHORIZED, [
682
+ "The sync remote rejected FORGELOOP_SYNC_TOKEN, or the token is not allowed for this repository.",
683
+ "Use a token whose SHA-256 hash the remote owner configured for this repository.",
684
+ ]],
685
+ [E_SYNC_CONFLICT, [
686
+ "The remote snapshot changed since this machine last pushed or pulled, so the push was refused instead of overwriting it.",
687
+ "Run forgeloop sync-pull --writers-quiesced --replace-active to adopt the remote state, then continue and push again.",
688
+ ]],
689
+ [E_SYNC_REMOTE, [
690
+ "The sync remote is unreachable, has no snapshot for this repository, or refused the request.",
691
+ "Check --remote and network access, push a first snapshot, or retry later.",
692
+ ]],
693
+ [E_SYNC_SNAPSHOT_INVALID, [
694
+ "The remote snapshot could not be decrypted with FORGELOOP_SYNC_KEY, belongs to another repository, or its contents failed integrity checks.",
695
+ "Use the same FORGELOOP_SYNC_KEY as the pushing machine; never restore a snapshot that fails these checks.",
696
+ ]],
697
+ [E_SYNC_TOO_LARGE, [
698
+ "The encrypted snapshot exceeds the 4 MiB sync limit.",
699
+ "Sync a project with less retained state; cloud sync does not split snapshots.",
700
+ ]],
701
+ ].map(([code, [meaning, safeResolution]]) => [code, Object.freeze({
702
+ code,
703
+ category: "cloud-sync",
704
+ classification: "PUBLIC_STABLE",
705
+ meaning,
706
+ safeResolution,
707
+ })])));
708
+
666
709
  const PERSISTENT_TRANSPORT_ERROR_METADATA = Object.freeze(Object.fromEntries([
667
710
  [E_PERSISTENT_TRANSPORT_FRAME_INVALID, [
668
711
  "The local persistent-search byte stream did not contain a complete valid JSON frame.",
@@ -720,6 +763,7 @@ export const PUBLIC_ERROR_CODES = Object.freeze({
720
763
  ...STRUCTURAL_QUALITY_ERROR_METADATA,
721
764
  ...ADVISORY_CONTEXT_AND_HANDOFF_ERROR_METADATA,
722
765
  ...REPOSITORY_INDEX_ERROR_METADATA,
766
+ ...CLOUD_SYNC_ERROR_METADATA,
723
767
  ...PERSISTENT_TRANSPORT_ERROR_METADATA,
724
768
  E_PREFLIGHT_NOT_READY: Object.freeze({
725
769
  code: "E_PREFLIGHT_NOT_READY",
@@ -1526,6 +1570,175 @@ export const E_BASELINE_RECORD_DURING_ACTIVE_TASK = "E_BASELINE_RECORD_DURING_AC
1526
1570
  export const E_POLICY_INITIALIZATION_FAILED = "E_POLICY_INITIALIZATION_FAILED";
1527
1571
  export const E_INIT_KIT_CONFLICT = "E_INIT_KIT_CONFLICT";
1528
1572
 
1573
+ /**
1574
+ * Codes emitted by runtime modules that do not yet have curated metadata.
1575
+ * They are published so integrators can recognise every code ForgeLoop can
1576
+ * return, but they carry no stable compatibility promise until promoted into
1577
+ * PUBLIC_ERROR_CODES. tests/error-registry-coverage.test.js keeps this list in
1578
+ * sync with the codes emitted under src/.
1579
+ */
1580
+ export const EMITTED_UNCLASSIFIED_ERROR_CODES = Object.freeze([
1581
+ "E_ACTION_AUTHORIZATION_REQUIRED",
1582
+ "E_ACTION_CAPABILITY_INVALID",
1583
+ "E_AUDIT_UX_INPUT_INVALID",
1584
+ "E_AUDIT_UX_INVALID_ERROR",
1585
+ "E_AUDIT_UX_OUTPUT_LIMIT",
1586
+ "E_BENCHMARK_INVALID",
1587
+ "E_BUNDLE_DIGEST_INVALID",
1588
+ "E_BUNDLE_PATH_INVALID",
1589
+ "E_BUNDLE_TASK_MISMATCH",
1590
+ "E_CHECK_BLOCKED",
1591
+ "E_CHECK_EXECUTION_PROVENANCE_MISSING",
1592
+ "E_CHECK_FAILED",
1593
+ "E_CHECK_REQUIRED",
1594
+ "E_COMMAND_EXECUTION_FAILED",
1595
+ "E_COMMAND_PROVENANCE_UNATTESTED",
1596
+ "E_COMMAND_UNSUPPORTED",
1597
+ "E_CONFIG_INVALID",
1598
+ "E_CONTINUITY_INCONSISTENT",
1599
+ "E_CONTRACT_INPUT_CONFLICT",
1600
+ "E_CONTRACT_PRESET_UNKNOWN",
1601
+ "E_CONTRACT_PROFILE_STRICT_UNVERIFIED",
1602
+ "E_CONTRACT_REVISION_UNSAFE",
1603
+ "E_CYCLE_CLOSED",
1604
+ "E_DECISION_BINDING_INVALID",
1605
+ "E_DECISION_IMMUTABLE",
1606
+ "E_DECISION_LEDGER_INVALID",
1607
+ "E_DISCOVERY_REQUIRED",
1608
+ "E_DUPLICATE_PROFILE_SOURCE",
1609
+ "E_EMULATED_SERVICES_CANCELLED",
1610
+ "E_EMULATED_SERVICES_CLEANUP_FAILED",
1611
+ "E_EMULATED_SERVICES_CONFIG_INVALID",
1612
+ "E_EMULATED_SERVICES_ENDPOINT_INVALID",
1613
+ "E_EMULATED_SERVICES_EXECUTION_FAILED",
1614
+ "E_EMULATED_SERVICES_OUTPUT_INVALID",
1615
+ "E_EMULATED_SERVICES_OUTPUT_LIMIT",
1616
+ "E_EMULATED_SERVICES_TIMEOUT",
1617
+ "E_EMULATED_SERVICES_UNAVAILABLE",
1618
+ "E_EMULATED_SERVICES_VERSION_UNSUPPORTED",
1619
+ "E_EVENT_INVALID",
1620
+ "E_EVIDENCE_BLOCKED",
1621
+ "E_EVIDENCE_MISSING",
1622
+ "E_EXECUTION_INVALID",
1623
+ "E_EXECUTION_PROFILE_CONTEXT_INVALID",
1624
+ "E_GATE_REVALIDATION_ACK_REQUIRED",
1625
+ "E_GATE_REVALIDATION_INVALID",
1626
+ "E_GATE_REVALIDATION_NOT_STALE",
1627
+ "E_GATE_REVALIDATION_PHASE_INVALID",
1628
+ "E_GATE_REVALIDATION_UNSAFE",
1629
+ "E_GATE_TASK_MISMATCH",
1630
+ "E_HIDDEN_KIT_MIGRATION_CONFLICT",
1631
+ "E_INITIAL_LIFECYCLE_INVALID",
1632
+ "E_INPUT_CONFLICT",
1633
+ "E_INSTALLATION_INVALID",
1634
+ "E_INTEGRATION_RESOURCE_UNKNOWN",
1635
+ "E_LEDGER_HASH_INVALID",
1636
+ "E_LEDGER_INVALID",
1637
+ "E_LEDGER_RELATION_INVALID",
1638
+ "E_LEDGER_SOURCE_INVALID",
1639
+ "E_LEDGER_STALE",
1640
+ "E_LEGACY_FILE_MIGRATION_CONFLICT",
1641
+ "E_MODEL_ROUTE_SAFETY_FLOOR_INVALID",
1642
+ "E_NATIVE_ADAPTER_MIGRATION_CONFLICT",
1643
+ "E_NEXT_ACTION_BLOCKED",
1644
+ "E_NO_INFORMATION_GAIN",
1645
+ "E_PHASE_ARTIFACT_STALE",
1646
+ "E_PHASE_EVIDENCE_MISSING",
1647
+ "E_PHASE_UNKNOWN",
1648
+ "E_PHASE_UNSUPPORTED",
1649
+ "E_POLICY_UNKNOWN",
1650
+ "E_PREFLIGHT_CONTRACT_STALE",
1651
+ "E_PREFLIGHT_READY_INCONSISTENT",
1652
+ "E_PREFLIGHT_ROUTE_STALE",
1653
+ "E_PREFLIGHT_TASK_MISMATCH",
1654
+ "E_PRODUCTION_READINESS_REQUIREMENT_PENDING",
1655
+ "E_PROFILE_MIGRATION_CONFLICT",
1656
+ "E_PROFILE_SOURCE_INVALID",
1657
+ "E_PROVIDER_AUTHORITY_ESCALATION",
1658
+ "E_PROVIDER_CAPABILITY_UNSUPPORTED",
1659
+ "E_PROVIDER_EXECUTION_FAILED",
1660
+ "E_PROVIDER_INVALID",
1661
+ "E_PROVIDER_OUTPUT_INVALID",
1662
+ "E_PROVIDER_OUTPUT_LIMIT",
1663
+ "E_PROVIDER_TIMEOUT",
1664
+ "E_PROVIDER_UNAVAILABLE",
1665
+ "E_REPOSITORY_GIT_COMMAND_FAILED",
1666
+ "E_REQUIRED_ARTIFACT_STALE",
1667
+ "E_REQUIREMENT_UNMET",
1668
+ "E_REVIEW_FINDING_REQUIRED",
1669
+ "E_ROUTE_PHASE_UNSUPPORTED",
1670
+ "E_STATE_INVALID",
1671
+ "E_STATE_LEDGER_MISMATCH",
1672
+ "E_STATE_REVISION_CONFLICT",
1673
+ "E_STATE_UNREADABLE",
1674
+ "E_STORAGE_ARTIFACT_BYTES_UNAVAILABLE",
1675
+ "E_STORAGE_ARTIFACT_INVALID",
1676
+ "E_STORAGE_ASYNC_TRANSACTION",
1677
+ "E_STORAGE_ATTACHMENT_INVALID",
1678
+ "E_STORAGE_BACKUP_INVALID",
1679
+ "E_STORAGE_BUSY",
1680
+ "E_STORAGE_CATALOG_CHANGED",
1681
+ "E_STORAGE_CONFIGURATION_INVALID",
1682
+ "E_STORAGE_CORRUPT",
1683
+ "E_STORAGE_EXPORT_DESTINATION",
1684
+ "E_STORAGE_EXPORT_IDENTITY",
1685
+ "E_STORAGE_EXPORT_UNSUPPORTED",
1686
+ "E_STORAGE_FULL",
1687
+ "E_STORAGE_IMPORT_ABORTED",
1688
+ "E_STORAGE_IMPORT_DESTINATION_EXISTS",
1689
+ "E_STORAGE_IMPORT_FAILED",
1690
+ "E_STORAGE_IMPORT_IDENTITY_COLLISION",
1691
+ "E_STORAGE_IMPORT_NAMESPACE_INVALID",
1692
+ "E_STORAGE_IMPORT_SIGNATURE_UNMAPPED",
1693
+ "E_STORAGE_IMPORT_SINGLETON_UNSUPPORTED",
1694
+ "E_STORAGE_INTEGRITY_INVALID",
1695
+ "E_STORAGE_INTERRUPTED",
1696
+ "E_STORAGE_MAINTENANCE_IN_PROGRESS",
1697
+ "E_STORAGE_MAINTENANCE_OWNER_INVALID",
1698
+ "E_STORAGE_METADATA_INVALID",
1699
+ "E_STORAGE_MIGRATION_ACTIVATION_INVALID",
1700
+ "E_STORAGE_MIGRATION_ARCHIVE_INVALID",
1701
+ "E_STORAGE_MIGRATION_BUSY",
1702
+ "E_STORAGE_MIGRATION_CAPTURE_INVALID",
1703
+ "E_STORAGE_MIGRATION_DESTINATION_INVALID",
1704
+ "E_STORAGE_MIGRATION_PARITY_INVALID",
1705
+ "E_STORAGE_MIGRATION_PUBLICATION_INVALID",
1706
+ "E_STORAGE_MIGRATION_QUIESCENCE_REQUIRED",
1707
+ "E_STORAGE_MIGRATION_REQUIRED",
1708
+ "E_STORAGE_MIGRATION_SOURCE_CHANGED",
1709
+ "E_STORAGE_MIGRATION_SOURCE_INVALID",
1710
+ "E_STORAGE_MIGRATION_TERMINAL_INVALID",
1711
+ "E_STORAGE_MIGRATION_UNMAPPED_SOURCE",
1712
+ "E_STORAGE_MIGRATION_VALIDATION_FAILED",
1713
+ "E_STORAGE_OBSERVATION_INCOMPLETE",
1714
+ "E_STORAGE_OPERATION_UNSUPPORTED",
1715
+ "E_STORAGE_PAYLOAD_MISMATCH",
1716
+ "E_STORAGE_READ_ONLY",
1717
+ "E_STORAGE_RESTORE_INVALID",
1718
+ "E_STORAGE_RUNTIME_CLOSED",
1719
+ "E_STORAGE_RUNTIME_CONFIGURATION_INVALID",
1720
+ "E_STORAGE_SNAPSHOT_TRANSACTION",
1721
+ "E_STORAGE_SOURCE_ROLLBACK_INVALID",
1722
+ "E_STORAGE_SOURCE_ROLLBACK_VALIDATION_INVALID",
1723
+ "E_STORAGE_TOPOLOGY_UNSUPPORTED",
1724
+ "E_STORAGE_TRANSACTION_EXPIRED",
1725
+ "E_STORAGE_TRANSACTION_INVALID",
1726
+ "E_STORAGE_TRANSACTION_LEAKED",
1727
+ "E_STORAGE_UNSUPPORTED_RUNTIME",
1728
+ "E_STORAGE_VERSION_MARKER_INVALID",
1729
+ "E_STORAGE_VERSION_UNSUPPORTED",
1730
+ "E_TARGET_REQUIRED",
1731
+ "E_TASK_CLAIM_CONFLICT",
1732
+ "E_TASK_ID_MISMATCH",
1733
+ "E_TASK_LOCK_STATE_UNKNOWN",
1734
+ "E_TASK_PHASE_INVALID",
1735
+ "E_TEST_ID_UNKNOWN",
1736
+ "E_TEST_PRUNE_BLOCKED",
1737
+ "E_TRANSACTION_INCOMPLETE",
1738
+ "E_UNRESOLVED_DECISION",
1739
+ "E_VERIFICATION_CHECK_REQUIRED",
1740
+ ]);
1741
+
1529
1742
  export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
1530
1743
  ...FAILURE_CODES,
1531
1744
  E_VERIFICATION_TOOL_UNAVAILABLE,
@@ -1585,6 +1798,8 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
1585
1798
  E_ATTESTATION_CONTENT_MISMATCH,
1586
1799
  E_ATTESTATION_SCOPE_MISMATCH,
1587
1800
  E_ATTESTATION_COVERAGE_GAP,
1801
+ E_EVIDENCE_BUNDLE_INVALID,
1802
+ E_EVIDENCE_EXPORT_UNAVAILABLE,
1588
1803
  E_ATTESTATION_COVERAGE_CONFLICT,
1589
1804
  E_ATTESTATION_STATEMENT_MISSING,
1590
1805
  E_ATTESTATION_STATEMENT_INVALID,
@@ -1685,6 +1900,12 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
1685
1900
  E_BASELINE_RECORD_DURING_ACTIVE_TASK,
1686
1901
  E_POLICY_INITIALIZATION_FAILED,
1687
1902
  E_INIT_KIT_CONFLICT,
1903
+ E_SYNC_CONFIG,
1904
+ E_SYNC_UNAUTHORIZED,
1905
+ E_SYNC_CONFLICT,
1906
+ E_SYNC_REMOTE,
1907
+ E_SYNC_SNAPSHOT_INVALID,
1908
+ E_SYNC_TOO_LARGE,
1688
1909
  E_REPOSITORY_INDEX_PLATFORM_UNSUPPORTED,
1689
1910
  E_REPOSITORY_INDEX_ENGINE_MISSING,
1690
1911
  E_REPOSITORY_INDEX_ENGINE_DOWNLOAD_FAILED,
@@ -1791,20 +2012,29 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
1791
2012
  E_HANDOFF_STALE,
1792
2013
  E_HANDOFF_ALREADY_ACCEPTED,
1793
2014
  E_HANDOFF_ACCEPTANCE_INCONSISTENT,
2015
+ ...EMITTED_UNCLASSIFIED_ERROR_CODES,
1794
2016
  ]));
1795
2017
 
2018
+ const UNCLASSIFIED_ERROR_CODES = new Set(EMITTED_UNCLASSIFIED_ERROR_CODES);
2019
+
1796
2020
  /**
1797
2021
  * Complete public registry. Older callers can retain PUBLIC_ERROR_CODES while
1798
2022
  * documentation and compatibility handshakes enumerate every stable code.
1799
2023
  */
1800
2024
  export const PUBLIC_ERROR_REGISTRY = Object.freeze(
1801
2025
  Object.fromEntries([...ALL_KNOWN_ERROR_CODES].sort().map((code) => [code, Object.freeze(
1802
- PUBLIC_ERROR_CODES[code] ?? {
2026
+ PUBLIC_ERROR_CODES[code] ?? (UNCLASSIFIED_ERROR_CODES.has(code) ? {
2027
+ code,
2028
+ category: "protocol",
2029
+ classification: "PUBLIC_UNCLASSIFIED",
2030
+ meaning: "Emitted by ForgeLoop but not yet curated; the code name is the contract and it carries no stable compatibility promise.",
2031
+ safeResolution: "Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json.",
2032
+ } : {
1803
2033
  code,
1804
2034
  category: "protocol",
1805
2035
  classification: "PUBLIC_STABLE",
1806
2036
  meaning: "A ForgeLoop protocol validation or lifecycle condition was not satisfied.",
1807
2037
  safeResolution: "Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json.",
1808
- },
2038
+ }),
1809
2039
  )])),
1810
2040
  );
@@ -0,0 +1,72 @@
1
+ import { createHash } from "node:crypto";
2
+ import { canonicalFingerprint } from "../artifacts.js";
3
+ import { E_EVIDENCE_BUNDLE_INVALID } from "../error-codes.js";
4
+
5
+ // Portable evidence bundle: what a completed task can prove to a verifier that
6
+ // has only the repository checkout. Signed content is the exact attestation
7
+ // statement text; everything else is either bound to it (the code manifest) or
8
+ // informational (the summary).
9
+
10
+ export const EVIDENCE_BUNDLE_SCHEMA_VERSION = 1;
11
+ export const EVIDENCE_BUNDLE_KIND = "forgeloop-evidence-bundle";
12
+ export const DEFAULT_EVIDENCE_DIRECTORY = ".forgeloop-evidence";
13
+
14
+ export const EVIDENCE_REDACTIONS = Object.freeze([
15
+ "absolute-paths",
16
+ "command-argv",
17
+ "command-output",
18
+ "environment",
19
+ "ledger-events",
20
+ ]);
21
+
22
+ const TASK_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/u;
23
+
24
+ export function evidenceError(code, message, details = {}) {
25
+ return Object.assign(new Error(message), { code, ...details });
26
+ }
27
+
28
+ export function assertEvidenceTaskId(taskId) {
29
+ if (typeof taskId !== "string" || !TASK_ID_PATTERN.test(taskId)) {
30
+ throw evidenceError(E_EVIDENCE_BUNDLE_INVALID, `Invalid evidence task ID: ${taskId}`);
31
+ }
32
+ return taskId;
33
+ }
34
+
35
+ export function evidenceBundlePath(directory, taskId) {
36
+ return `${directory.replace(/\/+$/u, "")}/${assertEvidenceTaskId(taskId)}.json`;
37
+ }
38
+
39
+ export function evidenceBundleDigest(bundle) {
40
+ const { digest: _digest, ...body } = bundle;
41
+ return createHash("sha256").update(JSON.stringify(body)).digest("hex");
42
+ }
43
+
44
+ export function sealEvidenceBundle(body) {
45
+ return { ...body, digest: evidenceBundleDigest(body) };
46
+ }
47
+
48
+ export function serializeEvidenceBundle(bundle) {
49
+ return `${JSON.stringify(bundle, null, 2)}\n`;
50
+ }
51
+
52
+ function requireField(condition, message) {
53
+ if (!condition) throw evidenceError(E_EVIDENCE_BUNDLE_INVALID, message);
54
+ }
55
+
56
+ export function parseEvidenceBundle(text, expectedTaskId = null) {
57
+ let bundle;
58
+ try { bundle = JSON.parse(text); } catch { throw evidenceError(E_EVIDENCE_BUNDLE_INVALID, "Evidence bundle is not valid JSON"); }
59
+ requireField(bundle && typeof bundle === "object" && !Array.isArray(bundle), "Evidence bundle must be an object");
60
+ requireField(bundle.schemaVersion === EVIDENCE_BUNDLE_SCHEMA_VERSION, `Unsupported evidence bundle schemaVersion: ${bundle.schemaVersion}`);
61
+ requireField(bundle.kind === EVIDENCE_BUNDLE_KIND, "Evidence bundle kind is not forgeloop-evidence-bundle");
62
+ assertEvidenceTaskId(bundle.taskId);
63
+ requireField(expectedTaskId === null || bundle.taskId === expectedTaskId, `Evidence bundle taskId ${bundle.taskId} does not match its file name`);
64
+ requireField(typeof bundle.statement?.text === "string", "Evidence bundle is missing the statement text");
65
+ requireField(bundle.manifest && typeof bundle.manifest === "object", "Evidence bundle is missing the code manifest");
66
+ requireField(bundle.manifestFingerprint === canonicalFingerprint(bundle.manifest), "Evidence bundle manifest fingerprint does not match its manifest");
67
+ requireField(bundle.signature === null || (typeof bundle.signature?.bundleText === "string" && typeof bundle.signature?.provider === "string"), "Evidence bundle signature is malformed");
68
+ requireField(typeof bundle.digest === "string" && bundle.digest === evidenceBundleDigest(bundle), "Evidence bundle digest does not match its content");
69
+ let statement;
70
+ try { statement = JSON.parse(bundle.statement.text); } catch { throw evidenceError(E_EVIDENCE_BUNDLE_INVALID, "Evidence bundle statement text is not valid JSON"); }
71
+ return { bundle, statement };
72
+ }
@@ -0,0 +1,179 @@
1
+ import { mkdir, readFile } from "node:fs/promises";
2
+ import path from "node:path";
3
+ import { canonicalFingerprint, readJsonArtifact } from "../artifacts.js";
4
+ import { readAttestationStatement } from "../attestation.js";
5
+ import { resolveAttestationBundlePath } from "../attachment-paths.js";
6
+ import { readCodeManifest } from "../code-manifest.js";
7
+ import { validateEventLedger } from "../events.js";
8
+ import { E_EVIDENCE_EXPORT_UNAVAILABLE } from "../error-codes.js";
9
+ import { assertSafePath, ensureWithin, writeFileAtomic } from "../filesystem.js";
10
+ import { withSigningStatementFile } from "../signing/statement-file.js";
11
+ import { taskArtifactPath, taskAttestationStatementPath } from "../task-paths.js";
12
+ import { getPackageRoot } from "../templates.js";
13
+ import { withProjectReadSnapshot } from "../../storage/project-read-snapshot.js";
14
+ import { withOperationalAttachmentFile } from "../../storage/operational-attachments.js";
15
+ import {
16
+ DEFAULT_EVIDENCE_DIRECTORY,
17
+ EVIDENCE_BUNDLE_KIND,
18
+ EVIDENCE_BUNDLE_SCHEMA_VERSION,
19
+ EVIDENCE_REDACTIONS,
20
+ assertEvidenceTaskId,
21
+ evidenceBundlePath,
22
+ evidenceError,
23
+ sealEvidenceBundle,
24
+ serializeEvidenceBundle,
25
+ } from "./bundle-format.js";
26
+
27
+ async function packageVersion(packageRoot) {
28
+ return JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8")).version;
29
+ }
30
+
31
+ async function readStatementText(target, taskId) {
32
+ return withSigningStatementFile(target, taskAttestationStatementPath(taskId), (filename) => readFile(filename, "utf8"));
33
+ }
34
+
35
+ async function readSignatureText(target, taskId) {
36
+ let bundlePath;
37
+ try { bundlePath = resolveAttestationBundlePath(target, taskId); } catch { return null; }
38
+ try {
39
+ return await withOperationalAttachmentFile(target, bundlePath, taskId, (filename) => readFile(filename, "utf8"));
40
+ } catch {
41
+ return null;
42
+ }
43
+ }
44
+
45
+ async function readOptional(target, relativePath, schemaName, packageRoot) {
46
+ try { return (await readJsonArtifact(target, relativePath, schemaName, packageRoot)).value; } catch { return null; }
47
+ }
48
+
49
+ function checkSummary(receipt) {
50
+ return (Array.isArray(receipt?.checks) ? receipt.checks : []).map((check) => ({
51
+ id: check.id,
52
+ requirement: typeof check.requirement === "string" ? check.requirement : null,
53
+ status: check.status,
54
+ exitCode: Number.isInteger(check.exitCode) ? check.exitCode : null,
55
+ })).sort((left, right) => String(left.id).localeCompare(String(right.id)));
56
+ }
57
+
58
+ const PHASE_BOUNDARIES = Object.freeze([
59
+ ["planning", "TASK_RECEIVED", "EXECUTION_STARTED"],
60
+ ["executing", "EXECUTION_STARTED", "VERIFICATION_STARTED"],
61
+ ["verifying", "VERIFICATION_STARTED", "REVIEW_STARTED"],
62
+ ["reviewing", "REVIEW_STARTED", "COMPLETION_VALIDATED"],
63
+ ]);
64
+
65
+ function firstAt(events, name) {
66
+ const value = events.find((event) => event.event === name)?.at;
67
+ const time = value ? Date.parse(value) : Number.NaN;
68
+ return Number.isFinite(time) ? time : null;
69
+ }
70
+
71
+ // Informational lifecycle metrics from the task ledger. Self-reported and not
72
+ // cryptographically bound; harness and model are not recorded by the ledger.
73
+ export function lifecycleMetrics(events, receipt) {
74
+ const received = firstAt(events, "TASK_RECEIVED");
75
+ const completed = firstAt(events, "COMPLETION_VALIDATED");
76
+ const phaseDurationsMs = {};
77
+ for (const [phase, start, end] of PHASE_BOUNDARIES) {
78
+ const from = firstAt(events, start);
79
+ const to = firstAt(events, end);
80
+ if (from !== null && to !== null && to >= from) phaseDurationsMs[phase] = to - from;
81
+ }
82
+ const checks = Array.isArray(receipt?.checks) ? receipt.checks : [];
83
+ return {
84
+ bound: false,
85
+ receivedAt: received === null ? null : new Date(received).toISOString(),
86
+ completedAt: completed === null ? null : new Date(completed).toISOString(),
87
+ durationMs: received !== null && completed !== null && completed >= received ? completed - received : null,
88
+ phaseDurationsMs,
89
+ verificationCycles: events.filter((event) => event.event === "VERIFICATION_STARTED").length,
90
+ diagnoses: events.filter((event) => event.event === "DIAGNOSIS_RECORDED").length,
91
+ checksPassed: checks.filter((check) => check.status === "passed").length,
92
+ checksFailed: checks.filter((check) => check.status === "failed").length,
93
+ };
94
+ }
95
+
96
+ async function readLedgerEvents(target, taskId, packageRoot) {
97
+ try {
98
+ const ledger = await validateEventLedger(target, packageRoot, { taskId });
99
+ return ledger.valid ? ledger.events : [];
100
+ } catch {
101
+ return [];
102
+ }
103
+ }
104
+
105
+ function informationalSummary(contract, receipt) {
106
+ return {
107
+ bound: false,
108
+ note: "Informational projection of the contract and receipt; only the statement and manifest are cryptographically bound.",
109
+ objective: typeof contract?.objective === "string" ? contract.objective : null,
110
+ successCriteria: Array.isArray(contract?.successCriteria) ? contract.successCriteria.map(String) : [],
111
+ checks: checkSummary(receipt),
112
+ };
113
+ }
114
+
115
+ async function collectEvidence(target, taskId, packageRoot) {
116
+ let manifest;
117
+ let statement;
118
+ try {
119
+ manifest = await readCodeManifest({ target, packageRoot, taskId });
120
+ statement = await readAttestationStatement({ target, packageRoot, taskId });
121
+ } catch (error) {
122
+ throw evidenceError(E_EVIDENCE_EXPORT_UNAVAILABLE, `Task ${taskId} has no exportable attestation (${error.code ?? "unknown"}); complete it with attestation mode required and run attestation-create first`);
123
+ }
124
+ if (statement.value.predicate?.verification?.completion !== "VALID") {
125
+ throw evidenceError(E_EVIDENCE_EXPORT_UNAVAILABLE, `Task ${taskId} attestation does not record a VALID completion`);
126
+ }
127
+ const statementText = await readStatementText(target, taskId);
128
+ if (canonicalFingerprint(JSON.parse(statementText)) !== canonicalFingerprint(statement.value)) {
129
+ throw evidenceError(E_EVIDENCE_EXPORT_UNAVAILABLE, "Attestation statement bytes changed while exporting");
130
+ }
131
+ return {
132
+ manifest: manifest.value,
133
+ statementText,
134
+ signatureText: await readSignatureText(target, taskId),
135
+ contract: await readOptional(target, taskArtifactPath(taskId, "contract"), "current-contract", packageRoot),
136
+ receipt: await readOptional(target, taskArtifactPath(taskId, "receipt"), "execution-receipt", packageRoot),
137
+ events: await readLedgerEvents(target, taskId, packageRoot),
138
+ };
139
+ }
140
+
141
+ function assertRedacted(text, target) {
142
+ const absolute = path.resolve(target);
143
+ if (text.includes(absolute) || text.includes(absolute.replaceAll("\\", "/"))) {
144
+ throw evidenceError(E_EVIDENCE_EXPORT_UNAVAILABLE, "Evidence bundle would contain the absolute project path; refusing to export");
145
+ }
146
+ }
147
+
148
+ export async function exportEvidenceBundle({ target, taskId, packageRoot = getPackageRoot(), directory = DEFAULT_EVIDENCE_DIRECTORY } = {}) {
149
+ assertEvidenceTaskId(taskId);
150
+ const evidence = await withProjectReadSnapshot(target, () => collectEvidence(target, taskId, packageRoot));
151
+ const bundle = sealEvidenceBundle({
152
+ schemaVersion: EVIDENCE_BUNDLE_SCHEMA_VERSION,
153
+ kind: EVIDENCE_BUNDLE_KIND,
154
+ taskId,
155
+ forgeloopVersion: await packageVersion(packageRoot),
156
+ statement: { text: evidence.statementText },
157
+ manifest: evidence.manifest,
158
+ manifestFingerprint: canonicalFingerprint(evidence.manifest),
159
+ signature: evidence.signatureText === null ? null : { provider: "sigstore", bundleText: evidence.signatureText },
160
+ summary: informationalSummary(evidence.contract, evidence.receipt),
161
+ metrics: lifecycleMetrics(evidence.events, evidence.receipt),
162
+ redactions: [...EVIDENCE_REDACTIONS],
163
+ });
164
+ const text = serializeEvidenceBundle(bundle);
165
+ assertRedacted(text, target);
166
+ const relativePath = evidenceBundlePath(directory, taskId);
167
+ await mkdir(path.dirname(ensureWithin(target, relativePath)), { recursive: true });
168
+ await assertSafePath(target, relativePath);
169
+ await writeFileAtomic(ensureWithin(target, relativePath), text);
170
+ return {
171
+ schemaVersion: 1,
172
+ taskId,
173
+ path: relativePath,
174
+ digest: bundle.digest,
175
+ coveredPaths: bundle.manifest.entries.length,
176
+ signed: bundle.signature !== null,
177
+ redactions: bundle.redactions,
178
+ };
179
+ }
@@ -0,0 +1,40 @@
1
+ // Markdown projection of an evidence verification for CI step summaries and
2
+ // pull-request check runs. It never adds facts beyond the verification result.
3
+
4
+ const STATUS_LABEL = Object.freeze({
5
+ ATTESTED: "Verified and signed",
6
+ INTEGRITY_ONLY: "Consistent, unsigned",
7
+ NONE: "Not verified",
8
+ });
9
+
10
+ const escapeCell = (value) => String(value).replaceAll("|", "\\|").replaceAll("\n", " ");
11
+
12
+ function bundleRows(result) {
13
+ if (result.bundles.length === 0) return ["No evidence bundles changed in this range."];
14
+ return [
15
+ "| Task | Integrity | Signature | Matching entries |",
16
+ "| --- | --- | --- | --- |",
17
+ ...result.bundles.map((bundle) => `| \`${escapeCell(bundle.taskId)}\` | ${bundle.integrity} | ${bundle.signature.status} | ${bundle.matchingEntries}/${bundle.entries} |`),
18
+ ];
19
+ }
20
+
21
+ function listSection(title, items) {
22
+ if (items.length === 0) return [];
23
+ return ["", `### ${title}`, "", ...items.map((item) => `- ${item}`)];
24
+ }
25
+
26
+ export function formatEvidenceMarkdown(result) {
27
+ const icon = result.status === "VALID" ? "✅" : "❌";
28
+ return [
29
+ `## ${icon} ForgeLoop evidence: ${STATUS_LABEL[result.level] ?? result.level}`,
30
+ "",
31
+ `Status \`${result.status}\`, level \`${result.level}\`: ${result.coveredPaths}/${result.changedPaths} changed paths covered.`,
32
+ "",
33
+ ...bundleRows(result),
34
+ ...listSection("Uncovered paths", result.uncoveredPaths.map((value) => `\`${escapeCell(value)}\``)),
35
+ ...listSection("Superseded entries", result.superseded.map((item) => `\`${escapeCell(item.path)}\` from \`${item.taskId}\`, covered by ${item.supersededBy.map((id) => `\`${id}\``).join(", ")}`)),
36
+ ...listSection("Errors", result.errors.map((error) => `\`${error.code}\`: ${escapeCell(error.message)}`)),
37
+ ...listSection("Warnings", result.warnings),
38
+ "",
39
+ ].join("\n");
40
+ }