Task Loop Store + List/Get Parity — Contract (Phase 2G-c, Step 2G-c-b)

Status: Contract frozen (2G-c-b Auto, 2026-06-24). Read-only list/get for task loops, orchestrator graphs, and loop-scoped task instances. Implementation on branch feat/phase-2g-c-loop-contracts.

Related:

• docs/TASK-LOOPS-AND-ORCHESTRATOR-PLAN.md — frozen plan (2G-c-a); open decisions §9 resolved below.
• docs/TASK-STORE-CONTRACT-2G.md — one-time task store (unchanged method shapes; additive instance fields).
• scooling/docs/TASK-LOOP-ADAPTER-CONTRACT-2G-c.md — Scooling consumer boundary.
• scooling/docs/CROSS-REPO-COORDINATION.md — SD-2 (instance task ↔ run linkage).

Scope fence (2G-c-b): Canonical task_loop/v0 + orchestrator_graph/v0 schemas, store shape, read ops, starter fixtures (school-trip graph), seven-tier test matrix. No Hub routes, no CLI/MCP wiring, no live gate flips. Writes deferred to 2G-d + Tier 3.

Simple summary

Recurring jobs (school-trip packing, weekly check-ins) need a series template in Knowtation plus dated instance tasks that link back to the series. This contract defines that filing cabinet: task_loop/v0 series, optional orchestrator_graph/v0 for loop orchestrator handoffs, and extended task/v0 rows with loop_ref + occurrence_key. Read-only list/get mirrors the 2G-b task pattern.

Technical summary

Extend hub_flow_store.json vault buckets with task_loops[] and orchestrator_graphs[] beside existing tasks[]. New module lib/task/task-loop-store.mjs owns loop/graph read ops; task-store.mjs gains optional instance fields and loop_ref / occurrence_key list filters. v0 exposes read-only listTaskLoops, getTaskLoop, getOrchestratorGraph — contract + inert store only in 2G-c-b; Hub/CLI/MCP surfaces land with live gate (Tier 3).

Open decisions §9 — recorded defaults (2G-c-b)

1. Canonical record — knowtation.task_loop/v0

1.1 Recurrence shape (v0 pinned subset — OD-2)

calendar_anchor deferred until Phase 2H calendar anchor refs exist.

1.2 Id regexes

2. Instance extensions — knowtation.task/v0 (additive)

Optional fields on occurrence instance tasks (standalone one-time tasks omit or null):

Uniqueness: (vault, loop_ref, occurrence_key) unique when loop_ref set.

3. Orchestrator graph — knowtation.orchestrator_graph/v0 (OD-1)

4. Store module shape

{
  "vaults": {
    "<vault_id>": {
      "flows": [],
      "steps": [],
      "runs": [],
      "candidates": [],
      "projections": [],
      "tasks": [],
      "task_loops": [],
      "orchestrator_graphs": []
    }
  }
}

4.1 Read operations

4.2 Seeding — task-loops/starter/, orchestrator-graphs/starter/

Idempotent seed on first loop read (school-trip fixture graph — plan Appendix A):

Instance: task_school_trip_2026_w25 with loop_ref: loop_school_trip, occurrence_key: 2026-W25.

Graph: graph_school_trip linking all five loops.

5. Fail-closed rules

1. Read-only v0 — no POST/PATCH/DELETE on loops/graphs.
2. Titles untrusted — never interpreted as commands.
3. Memory links = pointers only — no note bodies.
4. Scope deny-by-default — same model as tasks/flows.
5. Lazy materialization — store does not auto-spawn instances in 2G-c-b (fixture seed only).

6. Seven-tier test matrix (2G-c-b)

Cross-repo I-T-LOOP-01: loop_school_trip → task_school_trip_2026_w25 with matching loop_ref / occurrence_key.

7. Acceptance (2G-c-b)

• [x] Schema, store shape, read ops, OD defaults, fail-closed rules frozen here.
• [ ] lib/task/task-loop-store.mjs + extended task-store.mjs implement to this contract.
• [ ] Seven-tier tests green on feature branch.
• [ ] Hub routes not mounted until Tier 3 live gate.

Non-goals (2G-c-b)

• Hub/CLI/MCP route wiring (follows TASK_LOOP_LIVE_READ_AUTHORIZED Tier 3).
• Instance materialization writes (2G-d).
• Hosted canister loop index.
• RRULE full parser (2G-f).