owlrunkit 0.19.2 → 0.21.0

package/packages/attest/consumer-surface-v3.json

@@ -0,0 +1,275 @@
+{
+  "schemaVersion": "OwlCodaRunKitConsumerSurfaceManifestV3",
+  "consumerSurface": "unsigned_v3",
+  "status": "candidate",
+  "commands": [
+    {
+      "id": "quick_verify",
+      "invocation": "npx --no-install owlrunkit quick-verify --workspace <controller> [--foreign-workspace <frozen-git-worktree>] [--isolate] [--dependency-root <path>] [--bind-ignored <path>...] -- <executable> [args...]",
+      "lane": "Quick Verification",
+      "mutation": "writes receipt and output artifacts only under the controller workspace; foreign target state is observed before and after",
+      "runKitControlPlaneNetworkRequests": 0,
+      "childCommandNetworkPolicy": "caller_owned_not_restricted_or_measured",
+      "authorizationGranted": false
+    },
+    {
+      "id": "attest",
+      "invocation": "owlcoda attest <receipt> --workspace <path> [--json]",
+      "lane": "read-only consumer",
+      "mutation": "none",
+      "networkRequests": 0,
+      "authorizationGranted": false
+    },
+    {
+      "id": "resolve",
+      "invocation": "owlcoda resolve <reference> --store <path> [--store <path>...] [--workspace <path>] [--json]",
+      "lane": "read-only consumer",
+      "mutation": "none",
+      "networkRequests": 0,
+      "authorizationGranted": false
+    },
+    {
+      "id": "repair",
+      "invocation": "owlcoda runkit repair --run-id <run-id> [--json]",
+      "lane": "Formal Delivery recovery",
+      "mutation": "appends a repair plan, attempt, replacement packet, and receipt lineage when authorized by the active execution",
+      "runKitControlPlaneNetworkRequests": 0,
+      "childCommandNetworkPolicy": "caller_owned_not_restricted_or_measured",
+      "authorizationGranted": false
+    },
+    {
+      "id": "store_export",
+      "invocation": "owlcoda runkit store export --receipt <path> --output <path> [--json]",
+      "lane": "offline transfer producer",
+      "mutation": "creates one new exact-byte offline bundle and refuses overwrite",
+      "networkRequests": 0,
+      "authorizationGranted": false
+    },
+    {
+      "id": "store_import",
+      "invocation": "owlcoda runkit store import --bundle <path> --store <path> [--json]",
+      "lane": "offline transfer consumer",
+      "mutation": "imports exact receipt bytes idempotently and refuses byte conflicts",
+      "networkRequests": 0,
+      "authorizationGranted": false
+    },
+    {
+      "id": "local_metrics",
+      "invocation": "owlcoda runkit metrics --local [--json]",
+      "lane": "local inspection",
+      "mutation": "none",
+      "networkRequests": 0,
+      "authorizationGranted": false
+    },
+    {
+      "id": "standalone_attest",
+      "invocation": "owlcoda-attest attest <receipt-or-bundle.json> [--workspace <path>] [--json]",
+      "lane": "standalone read-only consumer",
+      "mutation": "none",
+      "networkRequests": 0,
+      "authorizationGranted": false
+    },
+    {
+      "id": "standalone_resolve",
+      "invocation": "owlcoda-attest resolve <attestation-ref.json> --store <path> [--store <path>...] [--workspace <path>] [--json]",
+      "lane": "standalone read-only consumer",
+      "mutation": "none",
+      "networkRequests": 0,
+      "authorizationGranted": false
+    }
+  ],
+  "schemas": [
+    "OwlCodaAttestationRefV1",
+    "OwlCodaAttestationResultV1",
+    "OwlCodaOfflineAttestationBundleV1",
+    "OwlCodaQuickVerificationReceiptV1",
+    "OwlCodaQuickVerificationReceiptV2",
+    "OwlCodaQuickVerificationReceiptV3",
+    "OwlCodaRunKitPublicVerificationBundleV1",
+    "OwlCodaWorkspaceSnapshotV1",
+    "OwlCodaWorkspaceSnapshotV2",
+    "OwlCodaQuickVerificationReceiptV4",
+    "OwlCodaRunKitCanonicalCandidateIdentityV1",
+    "OwlCodaRunKitForeignWorkspaceFilesystemIdentityV1"
+  ],
+  "attestationReference": {
+    "schemaVersion": "OwlCodaAttestationRefV1",
+    "requiredKeys": [
+      "schemaVersion",
+      "receiptId",
+      "receiptSha256",
+      "coreIdentity"
+    ],
+    "coreIdentityRequiredKeys": [
+      "contractVersion",
+      "coreManifestSha256"
+    ],
+    "additionalProperties": false,
+    "locationHints": false
+  },
+  "outcomes": {
+    "attestationDecisions": [
+      "GO",
+      "NO_GO",
+      "INDETERMINATE"
+    ],
+    "resolutionStatuses": {
+      "resolved_valid": 0,
+      "resolved_invalid": 1,
+      "resolved_indeterminate": 3,
+      "ambiguous": 1,
+      "not_found": 3
+    }
+  },
+  "assurance": {
+    "quickLane": "captured_verification",
+    "formalLane": "receipt_backed_delivery",
+    "quickCanSatisfyFormalAcceptance": false,
+    "signatureRequired": false,
+    "signatureAbsentIssueCode": "signature_absent",
+    "quickWithoutWorkspace": {
+      "otherwiseValidDecision": "INDETERMINATE",
+      "deterministicallyInvalidDecision": "NO_GO"
+    },
+    "independentReviewRequiredForFormalHighRisk": true,
+    "authorizationDerivedFromReceipt": false,
+    "foreignQuick": {
+      "controllerArtifactsOnly": true,
+      "targetExecutionMode": "disposable_consumer",
+      "targetStateBinding": "canonical_candidate_and_bounded_filesystem_before_after",
+      "zeroWriteClaim": "observed_governed_target_state_unchanged",
+      "absoluteOrTransientWriteAbsenceProved": false
+    }
+  },
+  "compatibility": {
+    "policy": "N verifies N and declared N-1 producer identities; N-1 is not required to trust an undeclared future producer identity",
+    "historicalBytesRewritten": false,
+    "scenarios": [
+      {
+        "id": "clean_first_use",
+        "evidencePath": "scripts/runkit-wave1-fresh-checkout-smoke.mjs"
+      },
+      {
+        "id": "dirty_workspace",
+        "evidencePath": "tests/runkit-contract/quick-verification.workflow.test.mjs"
+      },
+      {
+        "id": "offline_export_import_resolve",
+        "evidencePath": "tests/runkit-contract/wave4-offline-store.test.mjs"
+      },
+      {
+        "id": "n_minus_one_upgrade",
+        "evidencePath": "tests/runkit-contract/wave4-distribution-compatibility.test.mjs"
+      },
+      {
+        "id": "rollback",
+        "evidencePath": "tests/runkit-contract/wave4-distribution-compatibility.test.mjs"
+      },
+      {
+        "id": "historical_unsigned_receipt",
+        "evidencePath": "tests/runkit-contract/wave4-distribution-compatibility.test.mjs"
+      },
+      {
+        "id": "source_drift_repair",
+        "evidencePath": "tests/runkit-contract/repair-execution.workflow.test.mjs"
+      },
+      {
+        "id": "failed_repair_lineage",
+        "evidencePath": "tests/runkit-contract/repair-execution.workflow.test.mjs"
+      }
+    ]
+  },
+  "privacy": {
+    "defaultNetworkRequests": 0,
+    "defaultNetworkRequestsScope": "RunKit control plane only; a captured or replayed child command is caller-owned, unrestricted, and unmeasured",
+    "telemetry": false,
+    "credentialsRequired": false,
+    "hostedServiceRequired": false,
+    "receiptContentsMayContainCommandArgumentsAndPaths": true,
+    "operatorMustReviewBeforeExternalSharing": true
+  },
+  "metrics": {
+    "command": "owlcoda runkit metrics --local [--json]",
+    "localOnly": true,
+    "optInInspection": true,
+    "telemetry": false,
+    "networkRequests": 0,
+    "performanceTarget": false,
+    "automaticallyRecordsIndependentConsumption": false,
+    "statement": "Local totals describe project receipt state; independent consumption is evidenced by caller-owned attestation results, never hidden instrumentation."
+  },
+  "issueCodes": {
+    "ACCEPTED_AUTHORITY_GRANTED": "A Formal bundle marked accepted while its closeout grants authority.",
+    "ACCEPTED_RECEIPT_NOT_PASSED": "A Formal bundle marked accepted while its active receipt did not pass.",
+    "ACTIVE_RECEIPT_CONTEXT_BINDING_MISMATCH": "The active Formal receipt context does not match the declared verification context.",
+    "ACTIVE_RECEIPT_SOURCE_BINDING_MISMATCH": "The active Formal receipt source does not match the declared source fingerprint.",
+    "CANONICAL_JSON_INVALID": "Canonical JSON computation failed at a public Formal artifact boundary.",
+    "CLOSEOUT_ACTIVE_RECEIPT_MISMATCH": "The Formal closeout does not bind the active receipt.",
+    "CLOSEOUT_CONTEXT_BINDING_MISMATCH": "The Formal closeout context does not bind the declared verification context.",
+    "CLOSEOUT_SOURCE_BINDING_MISMATCH": "The Formal closeout source does not bind the declared source fingerprint.",
+    "DUPLICATE_OBJECT_KEY": "A Formal JSON input contains a duplicate object key.",
+    "EXTERNAL_AUTHORITY_GRANTED": "A public Formal bundle attempts to grant external authority.",
+    "INPUT_FILE_INVALID": "A Formal verifier input file cannot be read under the public file boundary.",
+    "INPUT_JSON_INVALID": "A Formal verifier input is not strict valid JSON.",
+    "INPUT_SIZE_LIMIT_EXCEEDED": "A Formal verifier input exceeds the deterministic byte limit.",
+    "JSON_NESTING_LIMIT_EXCEEDED": "A Formal verifier input exceeds the deterministic nesting limit.",
+    "JSON_NODE_LIMIT_EXCEEDED": "A Formal verifier input exceeds the deterministic JSON node limit.",
+    "PUBLIC_BUNDLE_SHAPE_INVALID": "A Formal public bundle has an unknown, missing, or extra field.",
+    "RECEIPT_AUTHORITY_GRANTED": "A Formal receipt attempts to grant external authority.",
+    "RECEIPT_COUNT_LIMIT_EXCEEDED": "A Formal bundle exceeds the deterministic receipt-count limit.",
+    "RECEIPT_ID_DUPLICATE": "A Formal receipt identifier appears more than once.",
+    "RECEIPT_LINEAGE_CYCLE": "Formal replacement lineage contains a cycle.",
+    "RECEIPT_LINEAGE_MULTIPLE_ACTIVE_LEAVES": "Formal replacement lineage has more than one active leaf.",
+    "RECEIPT_LINEAGE_NO_ACTIVE_LEAF": "Formal replacement lineage has no active leaf.",
+    "RECEIPT_LINEAGE_ORPHAN": "A Formal replacement references a parent absent from earlier append-only lineage.",
+    "SOURCE_FINGERPRINT_MISMATCH": "The Formal source payload does not match its declared fingerprint.",
+    "VERIFICATION_CONTEXT_FINGERPRINT_MISMATCH": "The Formal verification context does not match its declared fingerprint.",
+    "anchor_absent": "No external checkpoint or timestamp anchor was checked; unsigned V1 remains usable under local policy.",
+    "attestation_material_missing": "A receipt-bound output material is unavailable, so the result is indeterminate rather than silently accepted.",
+    "attestation_target_ambiguous": "More than one byte-distinct local receipt matches the reference.",
+    "attestation_target_not_found": "No receipt matching the exact local reference was found in the supplied stores.",
+    "bound_ignored_path_mutated_during_verification": "An explicitly bound ignored workspace path changed while the command ran.",
+    "consumer_source_mutated_during_verification": "The exact command changed Git-visible source in the disposable consumer.",
+    "core_identity_mismatch": "The receipt producer Core identity is not declared by this verifier.",
+    "current_workspace_not_checked": "No explicit workspace was selected, so Quick attestation did not read output paths or compare current checkout bytes.",
+    "dependency_environment_mutated_during_verification": "Bound dependency resolution metadata changed while the command ran.",
+    "quick_ignored_artifact_unbound": "Git-ignored outputs are not bound unless an explicit artifact contract names and hashes them.",
+    "quick_isolation_cleanup_failed": "The disposable consumer could not be removed after verification.",
+    "quick_receipt_store_invalid": "The project-local receipt store failed its path or file integrity boundary.",
+    "receipt_duplicate_key": "The receipt contains a duplicate JSON object key.",
+    "receipt_dependency_environment_mismatch": "Current bound dependency metadata differs from the receipt.",
+    "receipt_material_hash_mismatch": "A receipt-bound material differs from its recorded bytes, hash, or size.",
+    "receipt_schema_invalid": "The receipt does not satisfy the strict supported schema.",
+    "receipt_source_mismatch": "The selected workspace source does not match the receipt-bound source.",
+    "repair_plan_incomplete": "A deterministic repair plan cannot safely replay every required command and binding.",
+    "repair_replay_failed": "A replay command failed; the failed attempt and earlier lineage remain append-only.",
+    "signature_absent": "No receipt signature is present or checked; this is expected under unsigned V1 and proves no signer identity.",
+    "source_mutated_during_verification": "Source bytes changed while the command was running.",
+    "verification_command_failed": "The captured verification command did not exit successfully.",
+    "verification_context_mismatch": "The current runtime context differs from the receipt-bound runtime context.",
+    "foreign_workspace_mutated_during_verification": "The governed foreign target state changed while its isolated verification command ran."
+  },
+  "unsupportedClaims": [
+    "unsigned_receipt_proves_signer_identity",
+    "unsigned_receipt_proves_independent_machine_or_organization",
+    "issued_at_proves_trusted_wall_clock_time",
+    "unsigned_receipt_proves_external_existence_before_a_time",
+    "ignored_artifact_is_bound_without_explicit_artifact_contract",
+    "quick_receipt_proves_formal_acceptance",
+    "receipt_grants_git_release_or_business_authority",
+    "captured_or_replayed_child_command_has_zero_network",
+    "local_metrics_are_independent_consumption_events",
+    "foreign_quick_proves_absolute_or_transient_write_absence"
+  ],
+  "integration": {
+    "persist": "OwlCodaAttestationRefV1 plus the referenced receipt bytes",
+    "consume": "attest or resolve through a declared command or the standalone package",
+    "doNotImport": [
+      "private RunKit mutation Core",
+      "Desktop or App Server internals",
+      "project-private receipt-store layout"
+    ],
+    "futureSignedProfile": "additive; producer command and AttestationRefV1 shape remain unchanged"
+  },
+  "authorizationGranted": false
+}

package/packages/attest/distribution-manifest-v1.json

@@ -15,6 +15,9 @@
       "OwlCodaQuickVerificationReceiptV1",
       "OwlCodaQuickVerificationReceiptV2",
       "OwlCodaQuickVerificationReceiptV3",
+      "OwlCodaQuickVerificationReceiptV4",
+      "OwlCodaRunKitCanonicalCandidateIdentityV1",
+      "OwlCodaRunKitForeignWorkspaceFilesystemIdentityV1",
       "OwlCodaRunKitPublicVerificationBundleV1",
       "OwlCodaWorkspaceSnapshotV1",
       "OwlCodaWorkspaceSnapshotV2"
@@ -39,6 +42,21 @@
     "sha256": "sha256:3972dc9744f6499f0f9b2dbf76696f2ae7ad8af9b23dde66d6af86c9dfb36986"
   },
   "supportedProducerCoreIdentities": [
+    {
+      "contractVersion": "0.2",
+      "coreVersion": "0.21.0",
+      "coreManifestSha256": "sha256:f85b9bf8c32705d5f5dfebdb653e83ac8d1ac0468214c17f230cbd2de04246fd"
+    },
+    {
+      "contractVersion": "0.2",
+      "coreVersion": "0.20.1",
+      "coreManifestSha256": "sha256:8af2b9792731efa37f596255a7677dcec6e2fd3cc079dfdb0e6ff29e8017e784"
+    },
+    {
+      "contractVersion": "0.2",
+      "coreVersion": "0.20.0",
+      "coreManifestSha256": "sha256:30098aa9344c17c1ed0b5ed45ef1c590b3214b824402f584029c1ecb38ca7a70"
+    },
     {
       "contractVersion": "0.2",
       "coreVersion": "0.19.2",
@@ -164,6 +182,7 @@
     "cli/",
     "consumer-surface-v1.json",
     "consumer-surface-v2.json",
+    "consumer-surface-v3.json",
     "fixtures/",
     "LICENSE",
     "schemas/",

package/packages/attest/schemas/canonical-candidate-identity-v1.schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://owlcoda.dev/schemas/runkit/trust/canonical-candidate-identity-v1.schema.json",
+  "title": "OwlCoda RunKit Canonical Candidate Identity V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "manifestAlgorithmId",
+    "workspaceRoot",
+    "headCommit",
+    "trackedTree",
+    "gitVersion",
+    "discoveryCommand",
+    "discoveryEnvironment",
+    "ledger",
+    "ledgerByteLength",
+    "ledgerSha256",
+    "transportDiff",
+    "candidateFingerprint",
+    "authorizationGranted"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "OwlCodaRunKitCanonicalCandidateIdentityV1" },
+    "manifestAlgorithmId": { "const": "owlcoda-canonical-candidate-ledger-v1" },
+    "workspaceRoot": { "type": "string", "minLength": 1 },
+    "headCommit": { "$ref": "#/$defs/gitObject" },
+    "trackedTree": { "$ref": "#/$defs/gitObject" },
+    "gitVersion": { "type": "string", "minLength": 1 },
+    "discoveryCommand": {
+      "const": [
+        "git", "-c", "color.ui=false", "-c", "core.abbrev=40",
+        "status", "--porcelain=v1", "-z", "--untracked-files=all"
+      ]
+    },
+    "discoveryEnvironment": {
+      "const": {
+        "GIT_OPTIONAL_LOCKS": "0",
+        "LC_ALL": "C"
+      }
+    },
+    "ledger": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/ledgerEntry" }
+    },
+    "ledgerByteLength": { "type": "integer", "minimum": 2 },
+    "ledgerSha256": { "$ref": "#/$defs/hash" },
+    "transportDiff": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["exactArgv", "environment", "sizeBytes", "sha256", "identityRole"],
+      "properties": {
+        "exactArgv": {
+          "const": [
+            "git", "-c", "color.ui=false", "-c", "core.abbrev=40",
+            "diff", "--full-index", "--binary", "--no-ext-diff", "--no-textconv", "HEAD"
+          ]
+        },
+        "environment": {
+          "const": {
+            "GIT_OPTIONAL_LOCKS": "0",
+            "LC_ALL": "C"
+          }
+        },
+        "sizeBytes": { "type": "integer", "minimum": 0 },
+        "sha256": { "$ref": "#/$defs/hash" },
+        "identityRole": { "const": "transport_only" }
+      }
+    },
+    "candidateFingerprint": { "$ref": "#/$defs/hash" },
+    "authorizationGranted": { "const": false }
+  },
+  "$defs": {
+    "hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "gitObject": { "type": "string", "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$" },
+    "safePath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\)(?!.*\\u0000).+$"
+    },
+    "ledgerEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "previousPath", "operation", "status", "kind", "mode", "sizeBytes", "sha256"],
+      "properties": {
+        "path": { "$ref": "#/$defs/safePath" },
+        "previousPath": {
+          "oneOf": [
+            { "type": "null" },
+            { "$ref": "#/$defs/safePath" }
+          ]
+        },
+        "operation": { "enum": ["added", "copied", "deleted", "modified", "renamed"] },
+        "status": { "type": "string", "minLength": 2, "maxLength": 2 },
+        "kind": {
+          "oneOf": [
+            { "type": "null" },
+            { "enum": ["file", "gitlink", "symlink"] }
+          ]
+        },
+        "mode": { "type": ["integer", "null"], "minimum": 0, "maximum": 511 },
+        "sizeBytes": { "type": ["integer", "null"], "minimum": 0 },
+        "sha256": {
+          "oneOf": [
+            { "type": "null" },
+            { "$ref": "#/$defs/hash" }
+          ]
+        }
+      }
+    }
+  }
+}

package/packages/attest/schemas/foreign-workspace-filesystem-identity-v1.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://owlcoda.dev/schemas/runkit/trust/foreign-workspace-filesystem-identity-v1.schema.json",
+  "title": "OwlCoda RunKit Foreign Workspace Filesystem Identity V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "manifestAlgorithmId",
+    "workspaceRoot",
+    "excludedRoots",
+    "entryCount",
+    "totalFileBytes",
+    "ledgerByteLength",
+    "ledgerSha256",
+    "filesystemFingerprint"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "OwlCodaRunKitForeignWorkspaceFilesystemIdentityV1" },
+    "manifestAlgorithmId": { "const": "owlcoda-foreign-workspace-ledger-v1" },
+    "workspaceRoot": { "type": "string", "minLength": 1 },
+    "excludedRoots": { "const": [".git"] },
+    "entryCount": { "type": "integer", "minimum": 0 },
+    "totalFileBytes": { "type": "integer", "minimum": 0 },
+    "ledgerByteLength": { "type": "integer", "minimum": 2 },
+    "ledgerSha256": { "$ref": "#/$defs/hash" },
+    "filesystemFingerprint": { "$ref": "#/$defs/hash" }
+  },
+  "$defs": {
+    "hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+  }
+}