0%

per-project-graph-lifecycle

Per-Project Graph Lifecycle

Goal

  • Make a per-project intelligence graph a namespace-fenced, lease-owned, freshness-verified part of an activated project.

Files

  • CREATE scripts/harness_dist/graph_namespace.py
  • CREATE scripts/harness_dist/graph_lifecycle.py
  • MODIFY scripts/harness_dist/ai_os_contracts.py
  • MODIFY scripts/harness_dist/schemas/ai_os_contracts.schema.json
  • CREATE scripts/harness_dist/tests/test_graph_lifecycle.py

Third-domain contract

  • Graph state is a third lifecycle domain, distinct from immutable release bytes and from one-way project-data migrations.
  • Identity is an opaque namespace bound to canonical project identity, ingested source revision, and graph schema/runtime compatibility.
  • A shared service instance is permitted; isolation is namespace-fencing, never display name and never process reachability.

Grounding evidence

  • The live instance holds many tenants under Repo.name global uniqueness with (repo, ...) dependent identities and no project-root, worktree, or activation-generation identity; a display-name-keyed teardown would evict a co-tenant.
  • A top-level report of status: ok with stale: false coexists with independently stale per-facet generations across every tenant, so reachability and the global flag are both unsound readiness signals.

Verification

  • Write failing positive, negative, interruption, concurrency, and idempotency cases before implementation.
  • Pin the consumer-visible outcome through the real CLI/runtime entry point.
  • Run focused pytest and the owning runtime self-test with a 150-second test timeout.
  • Prove isolation under concurrent tenancy before any acceptance claim.

Work Items

  • Allocate a stable opaque graph namespace identity distinct from display repo name and filesystem path, and bind it to canonical project identity, the ingested source revision/worktree identity, and graph schema/runtime compatibility.
  • Register activation and root leases against that namespace; remove or rebuild namespace-scoped derived state only after the last durable reference is gone.
  • Define the required-facet readiness contract over per-namespace per-facet generations; acceptance asserts required query/facet readiness and never treats process reachability, a global stale flag, or Repo.name uniqueness as readiness.
  • Namespace-fence every read and write on a shared service instance, and prove isolation with concurrency tests for two projects sharing a basename, two worktrees of one repository, two releases requiring different graph schema compatibility, and a consumer whose basename collides with an existing reference-corpus tenant.
  • Define third-domain rollback: select a graph runtime/schema compatible with the target release, then retain, migrate, or rebuild project-scoped derived state; never blind-restore a snapshot and never tear down a shared instance holding other tenants.
  • Provision the graph for a consumer project that has none, so the graph-first rules the harness ships are satisfiable in every activated project.