IDKMesh

Specifications

These documents define IDKMesh’s versioned data, evaluation, repository-graph, and project-configuration contracts. A status of experimental means the contract can gain a new version; it does not permit silently changing the meaning of an existing version.

GitHub-First Product Operations

• GitHub-First Operations v0.1 — implementation contract for no-server GitHub coordination: bootstrap, durable run ledger, idempotency/recovery, multi-user claims/authority, Actions security, optional Projects/Pages/OIDC/attestations, and the pilot test matrix.
• GitHub Bootstrap Config Rendering v0.1 — deterministic C8-C rendering of the ProjectManifest seed, disabled secret-reference connector template, repository-local software-engineering DomainPack, generated ownership README, and content digests; rendering only, with no apply or GitHub mutation authority.
• GitHub Webhook Ingress v0.1 — authenticated bounded webhook envelope: raw-body HMAC-SHA256, event/action allowlists, repository binding, delivery provenance, and no dispatch authority.

Work and Evidence Contracts

• Benchmark Cohort Index v0.1 — freezes a replayable task set over existing WorkUnit and evaluator objects.
• CandidateReference v0.1 — binds a discovered PR or artifact bundle to an immutable provider-neutral candidate identity without granting verification or integration authority.
• Worker ResultManifest v0.1 — records worker-produced artifacts and claims without granting acceptance authority.
• Run Evidence Report v0.1 — aggregates attempt and independent-verification evidence for human inspection.
• Control Tower Local API v0.1 — versioned, loopback-only read API and presentation contract for Human Control Tower run evidence inspection, plus read-only Product Spine run, attempt, retained run-evidence (ADR-0024), and derived WorkUnit and project views (ADR-0021), the bounded service limits the development server enforces (ADR-0022), and the canonical event history and resumable SSE stream (ADR-0023).
• HTTP Service Runtime Baseline v0.1 — dependency-free request correlation, liveness/readiness, service metadata, payload-free structured access logging, and reusable bounded-limit primitives for IDKMesh HTTP surfaces.
• API Observability v0.1 — privacy-safe, fixed-cardinality request/status/latency/admission/concurrency telemetry, W3C traceparent v00 pass-through, and explicit local-profile SLO/alert targets. The OpenTelemetry exporter remains follow-up work under #744.
• Release Supply-Chain Baseline v0.1 — release SBOM/checksum/source-workflow identity evidence, immutable-pinned GitHub build provenance, consumer verification, and vulnerability/update policy for enterprise release integrity (#674).

• Verification Provenance Integrity — binds WorkUnit, result, and verification objects with canonical digests.

• Work Unit Composability Profile v0.2 — experimental reference profile adding the five-arm decomposition benchmark contract and a canonical WorkUnit DAG without changing either historical WorkUnit schema. Related: issues #3, #15, #17.
• Local Agent Execution Boundary v0.1 — fail-closed C4 contract separating canonical WorkUnit/AgentPreset admission, platform-specific sandbox enforcement, bounded outside-authority candidate capture, and provider-neutral ResultManifest normalization.

Evaluation Contracts

• Gate Audit v0.1 — the idkmesh gate-audit CLI contract: measures a verifier panel’s effective independent votes, correlation structure, and seeded-probe breach rate from a verdict matrix; diagnostic only, no acceptance authority.
• Marginal Evidence Analysis v0.1 — the idkmesh gate-marginal diagnostic contract: measures what one additional verifier changes for an already-selected panel under the exact same gate rule, with explicit censoring/uncertainty and no routing authority.
• Marginal Evidence Held-Out Benchmark v0.1 — the idkmesh gate-marginal-benchmark contract: freezes five design-only verifier-selection rules and evaluates them on disjoint holdout rows without emitting a production winner or routing decision.
• Marginal Evidence Cross-Cohort Synthesis v0.1 — the idkmesh gate-marginal-synthesis contract: aggregates a frozen set of held-out benchmark reports descriptively across cohorts while refusing duplicate evidence and emitting no strategy ranking or routing authority.
• Bound Unified-Diff Evaluator Backend — verifies untrusted patch bundles against an evaluator-owned plan.
• EvaluatorPlan v0.3 Semantic Matching — preserves the historical added-substring matching contract.

• EvaluatorPlan v0.4 Transition Semantics — requires both added and removed transition evidence.

• EvaluatorPlan v0.4 Calibrated Transformation Semantics — experimental P0 calibration contract for issue #157; adds a metadata-only transformation requirement so neither an exact-line false negative nor an inert-substring false positive passes.

Repository Graph Contracts

• IDKGraph Repository Mapping v0.1 — maps explicit repository structure into deterministic typed graph facts.
• IDKGraph P0 Observatory v0.1 — composes the read-only graph and health checks into one replayable command.
• IDKGraph P0 Residual Health Checks — defines warning-only orphan and accepted-decision linkage rules.
• GitHub to IDKGraph Projection v0.1 — deterministically joins normalized GitHub activity to the repository graph without granting write or execution authority.

API Conventions

• API Conventions v0.1 — frozen shared HTTP conventions for namespace/versioning, errors, correlation, pagination, idempotency, concurrency, events, limits, OpenAPI/schema compatibility, deprecation, and deployment security profiles. Frozen by issue #736 / ADR-0018; its error and list envelopes have canonical schemas under schemas/idkmesh-api-error-v0.1.schema.json and schemas/idkmesh-list-v0.1.schema.json.

Project Configuration

• Executor Admission v0.1 — readiness-checked atomic claims: the exact execution binding is derived and claimed in one operation, dispatch intent and submission revalidate the admission-time input snapshot, and changed upstream inputs fail closed. Local composition only; no dispatch, verification, acceptance or merge authority.

• Coordination Preflight v0.1 — read-only exact-input prerequisite readiness, replay/descendant invalidation, declared-effort capability advice and critical-path estimates; reuses the connector resolver and grants no admission/dispatch authority.

• Local Task Claims v0.1 — local SQLite atomic human/agent claims, immutable task limits, four deadlines, per-slot fencing and persistent unknown execution occupancy; no live provider or distributed ledger integration.

• Enterprise Control Profile v0.1 — experimental machine-readable enterprise posture and deterministic declaration-preflight contract for tenancy, identity/SoD, data/egress, secrets, audit, recovery, supply chain, and emergency change.
• ProjectManifest and DomainPack Interfaces — separates reusable coordination core from declarative domain and project policy.
• Connector Control API v0.1 — experimental project-facing connection, dispatch, run-state, webhook, secret-reference, agent/model-provider, and error contract above the canonical WorkUnit and verification semantics.
• Jules Trusted Source-Revision Binding — fail-closed comparison boundary that permits ScmRevisionBinding.verified=True only when the authorized repository/branch/revision matches independently observed SCM identity.
• Product Spine Service v0.1 — provider-neutral application-service contract that composes WorkUnit, routing, dispatch, candidate normalization, verification, evidence, and Human Decision Record without creating a new correctness or merge authority.
• Enterprise Tenant Scope v0.1 — tenant/project-scoped resource, storage-key, and idempotency foundation with fail-closed cross-scope reference checks.
• Enterprise Authorization Kernel v0.1 — strict ActorContext + RBAC/ABAC-style policy evaluation over exact tenant/project resource scope, including identity freshness, data clearance, risk floors, and distinct high-risk approval without executing the requested side effect. Also carries the trusted identity adapter contracts that may produce an ActorContext: E3-B from GitHub actor claims, E3-C from enterprise IdP (OIDC/SAML/SSO) claims. Neither adapter verifies a live credential.
• Enterprise Audit Ledger v0.1 — dedicated append-only SQLite security/audit evidence stream for E4: exact tenant/project, actor/service identity, authorization decision digest, immutable resource revision, outcome, retention, hash-chain integrity, checkpoint-based truncation detection, and a vendor-neutral SIEM/archive export sink. Audit evidence grants no action or integration authority.

When modifying a contract, update its schema, fixtures, implementation, and tests together. Introduce a new explicit version when behavior changes; keep old frozen evidence interpretable under its original meaning.

This site is open source. Improve this page.