okstra 0.231.0 → 0.232.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 (143) hide show
  1. package/README.md +15 -3
  2. package/dist/cli-registry.mjs +6 -0
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/memory/memory.mjs +9 -55
  5. package/dist/commands/memory/memory.mjs.map +1 -1
  6. package/dist/lib/memory-auto-register.d.mts +1 -0
  7. package/dist/lib/memory-auto-register.mjs +113 -0
  8. package/dist/lib/memory-auto-register.mjs.map +1 -0
  9. package/dist/lib/memory-entry-contract.d.mts +12 -0
  10. package/dist/lib/memory-entry-contract.mjs +46 -0
  11. package/dist/lib/memory-entry-contract.mjs.map +1 -0
  12. package/dist/lib/python-helper.d.mts +1 -1
  13. package/dist/lib/python-helper.mjs +3 -2
  14. package/dist/lib/python-helper.mjs.map +1 -1
  15. package/dist/lib/record-secrets.d.mts +1 -0
  16. package/dist/lib/record-secrets.mjs +28 -0
  17. package/dist/lib/record-secrets.mjs.map +1 -0
  18. package/dist/lib/types.d.mts +2 -1
  19. package/docs/architecture/storage-model.md +129 -2
  20. package/docs/architecture.md +11 -2
  21. package/docs/cli.md +234 -0
  22. package/docs/project-structure-overview.md +2 -1
  23. package/package.json +1 -1
  24. package/runtime/BUILD.json +2 -2
  25. package/runtime/agents/common.json +8 -8
  26. package/runtime/agents/roles/verifier.json +2 -4
  27. package/runtime/bin/okstra-provider-exec.py +10 -4
  28. package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
  29. package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
  30. package/runtime/prompts/coding-preflight/clean-code.md +85 -281
  31. package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
  32. package/runtime/prompts/coding-preflight/languages/java.md +3 -5
  33. package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
  34. package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
  35. package/runtime/prompts/coding-preflight/languages/python.md +2 -7
  36. package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
  37. package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
  38. package/runtime/prompts/coding-preflight/overview.md +25 -38
  39. package/runtime/prompts/coding-preflight/review-rules.json +30 -0
  40. package/runtime/prompts/duties/code-reviewer.json +15 -18
  41. package/runtime/prompts/duties/implementation-verifier.json +1 -0
  42. package/runtime/prompts/lead/convergence.md +3 -3
  43. package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
  44. package/runtime/prompts/lead/report-writer.md +1 -1
  45. package/runtime/prompts/lead/team-contract.md +1 -1
  46. package/runtime/prompts/profiles/_clarification-recommendation.md +3 -2
  47. package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
  48. package/runtime/python/okstra_ctl/agent/invocation.py +121 -36
  49. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +6 -0
  50. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +30 -4
  51. package/runtime/python/okstra_ctl/agent/standalone.py +3 -0
  52. package/runtime/python/okstra_ctl/analysis_packet.py +2 -19
  53. package/runtime/python/okstra_ctl/approval_decisions.py +16 -0
  54. package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
  55. package/runtime/python/okstra_ctl/business_flow/invocation.py +35 -3
  56. package/runtime/python/okstra_ctl/code_review_census.py +71 -7
  57. package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
  58. package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
  59. package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
  60. package/runtime/python/okstra_ctl/code_review_scope.py +36 -9
  61. package/runtime/python/okstra_ctl/code_review_target.py +85 -11
  62. package/runtime/python/okstra_ctl/consumers.py +12 -9
  63. package/runtime/python/okstra_ctl/convergence.py +112 -20
  64. package/runtime/python/okstra_ctl/convergence_engine.py +1 -0
  65. package/runtime/python/okstra_ctl/convergence_provenance.py +27 -11
  66. package/runtime/python/okstra_ctl/correction_round.py +6 -1
  67. package/runtime/python/okstra_ctl/design_review.py +207 -0
  68. package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
  69. package/runtime/python/okstra_ctl/dispatch_checkpoints.py +28 -5
  70. package/runtime/python/okstra_ctl/dispatch_core.py +3 -11
  71. package/runtime/python/okstra_ctl/doctor.py +8 -25
  72. package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
  73. package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
  74. package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
  75. package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
  76. package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
  77. package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
  78. package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
  79. package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
  80. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
  81. package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
  82. package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
  83. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +261 -0
  84. package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
  85. package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
  86. package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
  87. package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
  88. package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
  89. package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
  90. package/runtime/python/okstra_ctl/json_boundary.py +21 -2
  91. package/runtime/python/okstra_ctl/jsonl.py +21 -0
  92. package/runtime/python/okstra_ctl/manager_cli.py +26 -0
  93. package/runtime/python/okstra_ctl/manager_registration.py +29 -0
  94. package/runtime/python/okstra_ctl/manager_sync.py +3 -22
  95. package/runtime/python/okstra_ctl/model_io/renderers.py +13 -2
  96. package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
  97. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
  98. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +12 -2
  99. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +19 -6
  100. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +5 -3
  101. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +39 -11
  102. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
  103. package/runtime/python/okstra_ctl/phases/implementation/spec.md +26 -1
  104. package/runtime/python/okstra_ctl/phases/implementation/validation.py +86 -2
  105. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +4 -0
  106. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  107. package/runtime/python/okstra_ctl/report_assembly.py +15 -0
  108. package/runtime/python/okstra_ctl/report_narrative.py +3 -0
  109. package/runtime/python/okstra_ctl/report_prose_keys.py +7 -0
  110. package/runtime/python/okstra_ctl/report_synthesis_packet.py +19 -2
  111. package/runtime/python/okstra_ctl/review_policy.py +359 -0
  112. package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
  113. package/runtime/python/okstra_ctl/run.py +24 -1
  114. package/runtime/python/okstra_ctl/stage_done.py +11 -0
  115. package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
  116. package/runtime/python/okstra_ctl/team.py +3 -1
  117. package/runtime/python/okstra_ctl/verification_generation.py +23 -1
  118. package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
  119. package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
  120. package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
  121. package/runtime/python/okstra_ctl/verification_target.py +2 -0
  122. package/runtime/python/okstra_ctl/worker_dispatch.py +3 -1
  123. package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
  124. package/runtime/python/okstra_ctl/worker_runner.py +66 -10
  125. package/runtime/python/okstra_ctl/wrapper_status.py +16 -0
  126. package/runtime/python/okstra_ctl/write_policy.py +34 -1
  127. package/runtime/python/okstra_project/__init__.py +2 -0
  128. package/runtime/python/okstra_project/dirs.py +18 -0
  129. package/runtime/python/okstra_project/state.py +25 -20
  130. package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
  131. package/runtime/schemas/doyouknow-v1.schema.json +65 -0
  132. package/runtime/schemas/final-report-v2.0.schema.json +157 -0
  133. package/runtime/schemas/final-report-v3.0.schema.json +157 -0
  134. package/runtime/schemas/memory-entry-contract-v1.json +11 -0
  135. package/runtime/schemas/record-secret-patterns.json +41 -0
  136. package/runtime/skills/okstra-code-review/SKILL.md +71 -123
  137. package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
  138. package/runtime/skills/okstra-code-review/references/review-calibration.md +34 -54
  139. package/runtime/skills/okstra-manager/SKILL.md +7 -0
  140. package/runtime/skills/okstra-memory/SKILL.md +7 -0
  141. package/runtime/templates/implementation-worker-preamble.md +4 -9
  142. package/runtime/templates/worker-prompt-preamble.md +4 -12
  143. package/runtime/validators/validate-run.py +17 -8
@@ -0,0 +1,179 @@
1
+ from __future__ import annotations
2
+
3
+ from pathlib import Path
4
+ from collections.abc import Callable
5
+ from typing import TypedDict, cast
6
+
7
+ from ...json_boundary import JsonBoundaryError
8
+ from ...jsonl import parse_jsonl_snapshot
9
+ from ..config import SourceConfig, includes_group, includes_project
10
+ from ..contracts import DoyouknowError, Node, Relation, SecretRefusal, asset_object, canonical_json, record_secret_policy_digest
11
+ from ..identity import stable_id
12
+ from ..source_contracts import JsonValue, PreparedSource, SourceDomain, SourceRef, SourceScan, SourceSnapshot, validate_prepared_snapshot
13
+ from .io import read_source_text, safe_source_path
14
+
15
+ MAX_MEMORY_ROWS = 10_000
16
+ MAX_MEMORY_BODY_PREVIEW_CHARS = 1000
17
+ MEMORY_DOMAIN = SourceDomain("memory", "memory-book")
18
+
19
+
20
+ class MemoryEntry(TypedDict):
21
+ id: str
22
+ title: str
23
+ type: str
24
+ projectGroup: str
25
+ source: str
26
+ tags: list[str]
27
+ relatedProjects: list[str]
28
+ status: str
29
+ createdAt: str
30
+ archivedAt: str | None
31
+ path: str
32
+
33
+
34
+ class MemoryEntryContract(TypedDict):
35
+ schemaVersion: int
36
+ requiredStrings: list[str]
37
+ stringArrays: list[str]
38
+ nullableStrings: list[str]
39
+ optionalStrings: list[str]
40
+ enums: dict[str, list[str]]
41
+
42
+
43
+ def _memory_entry_contract() -> MemoryEntryContract:
44
+ contract = asset_object("memory-entry-contract-v1.json")
45
+ lists = ("requiredStrings", "stringArrays", "nullableStrings", "optionalStrings")
46
+ if type(contract.get("schemaVersion")) is not int or contract["schemaVersion"] != 1 or any(not isinstance(contract.get(key), list) or any(not isinstance(item, str) for item in contract[key]) for key in lists):
47
+ raise DoyouknowError("invalid Memory Book entry contract")
48
+ enums = contract.get("enums")
49
+ if not isinstance(enums, dict) or not {"type", "status"} <= enums.keys() or any(not isinstance(items, list) or not items or any(not isinstance(item, str) for item in items) for items in enums.values()):
50
+ raise DoyouknowError("invalid Memory Book entry contract")
51
+ return cast(MemoryEntryContract, contract)
52
+
53
+
54
+ def _is_memory_entry(row: dict, contract: MemoryEntryContract) -> bool:
55
+ return (
56
+ all(isinstance(row.get(key), str) for key in contract["requiredStrings"])
57
+ and all(isinstance(row.get(key), list) and all(isinstance(item, str) for item in row[key]) for key in contract["stringArrays"])
58
+ and all(key in row and (row[key] is None or isinstance(row[key], str)) for key in contract["nullableStrings"])
59
+ and all(key not in row or isinstance(row[key], str) for key in contract["optionalStrings"])
60
+ and all(isinstance(row.get(key), str) and row[key] in items for key, items in contract["enums"].items())
61
+ )
62
+
63
+
64
+ def _includes_memory_entry(entry: MemoryEntry, settings: SourceConfig) -> bool:
65
+ return (
66
+ includes_group(settings, entry["projectGroup"])
67
+ and (not settings["includeProjects"] or bool(entry["relatedProjects"]))
68
+ and all(includes_project(settings, project) for project in entry["relatedProjects"])
69
+ )
70
+
71
+
72
+ def _memory_snapshot(root: Path, entry: MemoryEntry, settings: SourceConfig, body: str) -> SourceSnapshot:
73
+ locator = safe_source_path(root, entry["path"]).as_uri()
74
+ projects = tuple(dict.fromkeys(entry["relatedProjects"]))
75
+ nodes: tuple[Node, ...] = tuple(
76
+ {"kind": "project", "scope": "okstra-project", "key": project, "title": project, "ref": f"project:{project}"}
77
+ for project in projects
78
+ )
79
+ relations: tuple[Relation, ...] = tuple(
80
+ {"from": "$source", "to": f"project:{project}", "kind": "related-project",
81
+ "reason": "Memory entry names this related project.", "evidence": [locator], "standing": "observed"}
82
+ for project in projects
83
+ )
84
+ metadata: dict[str, JsonValue] = {
85
+ **entry, "bodyPreview": body[:MAX_MEMORY_BODY_PREVIEW_CHARS],
86
+ "bodyTruncated": len(body) > MAX_MEMORY_BODY_PREVIEW_CHARS,
87
+ "bodyDigest": stable_id("memory-body", body),
88
+ }
89
+ snapshot = SourceSnapshot(
90
+ SourceRef("memory", "memory-book", entry["id"]),
91
+ {"kind": "artifact", "scope": "memory-book", "key": entry["id"], "title": entry["title"]},
92
+ locator, metadata, nodes=nodes, relations=relations,
93
+ lifecycle="archived" if entry["status"] == "archived" else "active",
94
+ source_updated_at=entry["archivedAt"] or entry["createdAt"], scope=settings["scope"],
95
+ )
96
+ return snapshot
97
+
98
+
99
+ def read_memory_source(home: Path, ref: SourceRef, settings: SourceConfig) -> PreparedSource:
100
+ try:
101
+ if ref.kind != "memory" or ref.owner_id != "memory-book":
102
+ raise DoyouknowError("memory reference has a different owner")
103
+ root = safe_source_path(home, "memory-book")
104
+ rows, damaged = parse_jsonl_snapshot(read_source_text(root, "index.jsonl"))
105
+ if len(rows) > MAX_MEMORY_ROWS:
106
+ raise DoyouknowError("memory index exceeds row limit")
107
+ selected = [row for row in rows if row.get("id") == ref.native_id]
108
+ contract = _memory_entry_contract()
109
+ if len(selected) != 1 or not _is_memory_entry(selected[0], contract):
110
+ raise DoyouknowError("memory reference is unavailable")
111
+ entry = cast(MemoryEntry, selected[0])
112
+ if not _includes_memory_entry(entry, settings):
113
+ return PreparedSource(ref, None, outcome="excluded")
114
+ body = read_source_text(root, entry["path"])
115
+ return _prepare_memory_snapshot(root, entry, settings, body, contract)
116
+ except (OSError, UnicodeError, DoyouknowError, JsonBoundaryError, RecursionError):
117
+ return PreparedSource(ref, None, outcome="unavailable", error_code="memory-source-unavailable")
118
+
119
+
120
+ def _prepare_memory_snapshot(root: Path, entry: MemoryEntry, settings: SourceConfig, body: str, contract: MemoryEntryContract) -> PreparedSource:
121
+ snapshot = _memory_snapshot(root, entry, settings, body)
122
+ fingerprint = stable_id("memory-registration", canonical_json(entry), snapshot.metadata["bodyDigest"], canonical_json(contract), canonical_json(settings["scope"]), record_secret_policy_digest())
123
+ return PreparedSource(snapshot.ref, fingerprint, snapshot, secret_texts=(body,))
124
+
125
+
126
+ def _memory_projection(root: Path, entry: MemoryEntry, settings: SourceConfig, contract: MemoryEntryContract, gate: Callable[[PreparedSource], bool] | None) -> tuple[SourceSnapshot | None, str | None]:
127
+ try:
128
+ body = read_source_text(root, entry["path"])
129
+ except (OSError, UnicodeError, DoyouknowError):
130
+ return None, "memory-body-unreadable"
131
+ try:
132
+ prepared = _prepare_memory_snapshot(root, entry, settings, body, contract)
133
+ if gate is not None:
134
+ if not gate(prepared):
135
+ return None, "memory-secret-refused"
136
+ else:
137
+ validate_prepared_snapshot(prepared)
138
+ return prepared.snapshot, None
139
+ except SecretRefusal:
140
+ return None, "memory-secret-refused"
141
+ except (OSError, UnicodeError, DoyouknowError, JsonBoundaryError):
142
+ return None, "memory-projection-unavailable"
143
+
144
+
145
+ def scan_memory_sources(home: Path, settings: SourceConfig, *, gate: Callable[[PreparedSource], bool] | None = None) -> SourceScan:
146
+ try:
147
+ root = safe_source_path(home, "memory-book")
148
+ if not root.exists():
149
+ return SourceScan(MEMORY_DOMAIN, (), (), "complete")
150
+ rows, invalid_lines = parse_jsonl_snapshot(read_source_text(root, "index.jsonl"))
151
+ except (OSError, UnicodeError, DoyouknowError):
152
+ return SourceScan(MEMORY_DOMAIN, (), (), "partial", ("memory-index-unreadable",))
153
+ try:
154
+ contract = _memory_entry_contract()
155
+ except (OSError, DoyouknowError, JsonBoundaryError):
156
+ return SourceScan(MEMORY_DOMAIN, (), (), "unavailable", ("memory-contract-unavailable",))
157
+ errors = [f"memory-index-invalid-line:{number}" for number in invalid_lines]
158
+ if len(rows) > MAX_MEMORY_ROWS:
159
+ errors.append("memory-index-row-limit")
160
+ snapshots: list[SourceSnapshot] = []
161
+ observed: dict[str, SourceRef] = {}
162
+ for row in rows[:MAX_MEMORY_ROWS]:
163
+ if not _is_memory_entry(row, contract) or not isinstance(row.get("id"), str) or not row["id"].strip():
164
+ errors.append("memory-index-invalid-entry")
165
+ continue
166
+ entry = cast(MemoryEntry, row)
167
+ if entry["id"] in observed:
168
+ errors.append("memory-index-duplicate-entry")
169
+ continue
170
+ observed[entry["id"]] = SourceRef("memory", "memory-book", entry["id"])
171
+ if not _includes_memory_entry(entry, settings):
172
+ continue
173
+ snapshot, error = _memory_projection(root, entry, settings, contract, gate)
174
+ if snapshot is not None:
175
+ snapshots.append(snapshot)
176
+ if error is not None:
177
+ errors.append(error)
178
+ return SourceScan(MEMORY_DOMAIN, tuple(snapshots), tuple(observed.values()),
179
+ "partial" if errors else "complete", tuple(errors))
@@ -0,0 +1,95 @@
1
+ from __future__ import annotations
2
+
3
+ from pathlib import Path
4
+
5
+ from okstra_project import StateError, parse_task_key, resolve_task_root_read_only
6
+ from okstra_project.dirs import PROJECT_JSON_RELATIVE, TASK_CATALOG_RELATIVE, TASK_MANIFEST_FILENAME, TASKS_RELATIVE
7
+ from okstra_project.state import derived_task_status
8
+
9
+ from ...json_boundary import JsonBoundaryError
10
+ from ..config import SourceConfig, includes_project
11
+ from ..contracts import DoyouknowError
12
+ from ..source_contracts import SourceDomain, SourceRef, SourceScan, SourceSnapshot, snapshot_payload
13
+ from .io import read_source_object, safe_source_path
14
+
15
+
16
+ def _task_snapshot(project_root: Path, project_id: str, task_key: str, catalog: list[dict], settings: SourceConfig) -> SourceSnapshot:
17
+ task_root = resolve_task_root_read_only(project_root, task_key, catalog=catalog)
18
+ if task_root is None:
19
+ raise DoyouknowError("project task is unavailable")
20
+ task_root = safe_source_path(project_root, task_root)
21
+ manifest_path = task_root / TASK_MANIFEST_FILENAME
22
+ manifest = read_source_object(project_root, manifest_path)
23
+ if manifest.get("projectId") != project_id or manifest.get("taskKey") != task_key:
24
+ raise DoyouknowError("project task identity does not match its source")
25
+ _, group, task_id = parse_task_key(task_key)
26
+ if manifest.get("taskGroup") != group or manifest.get("taskId") != task_id:
27
+ raise DoyouknowError("project task identity is inconsistent")
28
+ direct = manifest.get("latestWorkRecordPath")
29
+ metadata = {"projectId": project_id, "manifest": manifest, "status": derived_task_status(manifest)}
30
+ if direct:
31
+ path = safe_source_path(project_root, direct)
32
+ safe_source_path(task_root, path)
33
+ record = read_source_object(project_root, path)
34
+ if record.get("taskKey") != task_key:
35
+ raise DoyouknowError("direct work identity does not match its source")
36
+ metadata["directWork"] = record
37
+ project_node = {"kind": "project", "scope": "okstra-project", "key": project_id, "title": project_id, "ref": "project"}
38
+ snapshot = SourceSnapshot(
39
+ ref=SourceRef("task", project_id, task_key),
40
+ primary_node={"kind": "task", "scope": project_id, "key": task_key, "ref": "primary", "title": str(manifest.get("title") or task_id)},
41
+ locator=str(manifest_path), metadata=metadata, nodes=(project_node,),
42
+ relations=({"from": "$source", "to": "project", "kind": "belongs-to", "reason": "The project owns this task.", "evidence": [str(manifest_path)], "standing": "observed"},),
43
+ source_updated_at=manifest.get("workStatusUpdatedAt") or manifest.get("updatedAt"), scope=settings["scope"],
44
+ )
45
+ snapshot_payload(snapshot)
46
+ return snapshot
47
+
48
+
49
+ def _task_catalog(project_root: Path) -> list[dict] | None:
50
+ catalog_path = safe_source_path(project_root, TASK_CATALOG_RELATIVE)
51
+ try:
52
+ catalog_path.stat()
53
+ except FileNotFoundError:
54
+ try:
55
+ safe_source_path(project_root, TASKS_RELATIVE).stat()
56
+ except FileNotFoundError:
57
+ return None
58
+ catalog = read_source_object(project_root, catalog_path).get("tasks")
59
+ if not isinstance(catalog, list) or any(not isinstance(row, dict) for row in catalog):
60
+ raise DoyouknowError("project task catalog is invalid")
61
+ return catalog
62
+
63
+
64
+ def _catalog_task_key(row: dict, project_id: str) -> str:
65
+ task_key = row.get("taskKey", "")
66
+ if not isinstance(task_key, str):
67
+ raise DoyouknowError("project task key must be a string")
68
+ owner, _, _ = parse_task_key(task_key)
69
+ if owner != project_id:
70
+ raise DoyouknowError("project catalog identity does not match its source")
71
+ return task_key
72
+
73
+
74
+ def scan_project_tasks(project_root: Path, project_id: str, settings: SourceConfig) -> SourceScan:
75
+ domain = SourceDomain("task", project_id)
76
+ if "task" not in settings["sources"] or not includes_project(settings, project_id):
77
+ return SourceScan(domain, (), (), "partial")
78
+ snapshots, observed, errors = [], [], []
79
+ try:
80
+ project = read_source_object(project_root, PROJECT_JSON_RELATIVE)
81
+ if project.get("projectId") != project_id:
82
+ raise DoyouknowError("registered project identity does not match its source")
83
+ catalog = _task_catalog(project_root)
84
+ if catalog is None:
85
+ return SourceScan(domain, (), (), "complete")
86
+ for row in catalog:
87
+ try:
88
+ task_key = _catalog_task_key(row, project_id)
89
+ observed.append(SourceRef("task", project_id, task_key))
90
+ snapshots.append(_task_snapshot(project_root, project_id, task_key, catalog, settings))
91
+ except (DoyouknowError, JsonBoundaryError, OSError, StateError, TypeError, RecursionError):
92
+ errors.append("task-source-unavailable")
93
+ except (DoyouknowError, JsonBoundaryError, OSError, StateError, TypeError, RecursionError):
94
+ return SourceScan(domain, (), (), "unavailable", ("project-source-unavailable",))
95
+ return SourceScan(domain, tuple(snapshots), tuple(observed), "partial" if errors else "complete", tuple(errors))
@@ -0,0 +1,260 @@
1
+ from __future__ import annotations
2
+
3
+ import hashlib
4
+ import json
5
+ import sqlite3
6
+ import os
7
+ import tempfile
8
+ import time
9
+ from collections.abc import Iterator
10
+ from contextlib import closing, contextmanager
11
+ from datetime import datetime, timezone
12
+ from pathlib import Path
13
+
14
+ from .contracts import DoyouknowError, Envelope, canonical_json, validate_envelope
15
+ from .identity import node_id, stable_id
16
+ from .paths import database_path, ensure_storage_root, require_database_location as _require_database_location
17
+
18
+ SCHEMA_VERSION = 2
19
+ SQLITE_TIMEOUT_SECONDS = 5
20
+ SCHEMA_STATEMENTS = (
21
+ """create table if not exists node (
22
+ id text primary key,
23
+ kind text not null,
24
+ scope text not null,
25
+ canonical_key text not null,
26
+ title text not null,
27
+ unique(kind, scope, canonical_key)
28
+ )""",
29
+ """create table if not exists record (
30
+ id text primary key references node(id),
31
+ latest_revision text
32
+ )""",
33
+ """create table if not exists revision (
34
+ id text primary key,
35
+ record_id text not null references record(id),
36
+ previous_revision text references revision(id),
37
+ content_digest text not null,
38
+ source_kind text not null,
39
+ source_id text not null,
40
+ source_revision text not null,
41
+ created_at text not null,
42
+ payload text not null,
43
+ unique(record_id, source_kind, source_id, source_revision)
44
+ )""",
45
+ """create table if not exists relation (
46
+ id text primary key,
47
+ revision_id text not null references revision(id),
48
+ from_node text not null references node(id),
49
+ to_node text not null references node(id),
50
+ kind text not null,
51
+ reason text not null,
52
+ evidence text not null,
53
+ standing text not null
54
+ check(standing in ('observed', 'user-stated', 'candidate'))
55
+ )""",
56
+ """create table if not exists request (
57
+ id text primary key,
58
+ input_digest text not null,
59
+ record_id text not null references record(id),
60
+ revision_id text not null references revision(id)
61
+ )""",
62
+ )
63
+
64
+
65
+ def _initialize_database(connection: sqlite3.Connection, path: Path) -> None:
66
+ version = connection.execute("pragma user_version").fetchone()[0]
67
+ if version not in (0, 1, SCHEMA_VERSION):
68
+ raise DoyouknowError(f"unsupported doyouknow database version: {version}")
69
+ if version == 1:
70
+ _backup_database(path)
71
+ for statement in SCHEMA_STATEMENTS:
72
+ connection.execute(statement)
73
+ from .source_store import SOURCE_SCHEMA_STATEMENTS
74
+
75
+ for statement in SOURCE_SCHEMA_STATEMENTS:
76
+ connection.execute(statement)
77
+ connection.execute(f"pragma user_version = {SCHEMA_VERSION}")
78
+
79
+
80
+ def _backup_database(path: Path) -> Path:
81
+ descriptor, name = tempfile.mkstemp(prefix="graph-v1-", suffix=".sqlite3", dir=path.parent)
82
+ os.close(descriptor)
83
+ backup = Path(name)
84
+ deadline = time.monotonic() + SQLITE_TIMEOUT_SECONDS
85
+
86
+ def check_deadline(status: int, remaining: int, total: int) -> None:
87
+ if time.monotonic() >= deadline:
88
+ raise DoyouknowError("doyouknow database backup timed out")
89
+
90
+ try:
91
+ with closing(sqlite3.connect(path.as_uri() + "?mode=ro", uri=True, timeout=SQLITE_TIMEOUT_SECONDS)) as source:
92
+ with closing(sqlite3.connect(backup)) as destination:
93
+ source.backup(destination, pages=128, progress=check_deadline, sleep=0.01)
94
+ except (OSError, sqlite3.Error, ValueError):
95
+ backup.unlink(missing_ok=True)
96
+ raise
97
+ return backup
98
+
99
+
100
+ def _content_payload(envelope: Envelope) -> dict:
101
+ return {key: value for key, value in envelope.items() if key not in {"requestId", "expectedPreviousRevision"}}
102
+
103
+
104
+ def _digest(value: object) -> str:
105
+ return hashlib.sha256(canonical_json(value).encode("utf-8")).hexdigest()
106
+
107
+
108
+ def capture_record(envelope: Envelope, *, home: Path | None = None) -> dict:
109
+ return _persist_record(validate_envelope(envelope), database_path(home))
110
+
111
+
112
+ def ingest_source(envelope: Envelope, *, home: Path | None = None) -> dict:
113
+ return _persist_record(validate_envelope(envelope), database_path(home))
114
+
115
+
116
+ def _persist_record(envelope: Envelope, path: Path) -> dict:
117
+ with write_connection(path) as connection:
118
+ result = _write_record(connection, envelope)
119
+ return {"ok": True, **result, "path": str(path)}
120
+
121
+
122
+ @contextmanager
123
+ def write_connection(path: Path) -> Iterator[sqlite3.Connection]:
124
+ _require_database_location(path)
125
+ ensure_storage_root(path.parent)
126
+ try:
127
+ with closing(sqlite3.connect(path, timeout=SQLITE_TIMEOUT_SECONDS, isolation_level=None)) as connection:
128
+ connection.execute("pragma foreign_keys = on")
129
+ connection.execute("begin immediate")
130
+ try:
131
+ _initialize_database(connection, path)
132
+ yield connection
133
+ connection.commit()
134
+ except (sqlite3.Error, ValueError):
135
+ connection.rollback()
136
+ raise
137
+ except sqlite3.Error as exc:
138
+ raise DoyouknowError(f"doyouknow storage failed: {exc}") from exc
139
+
140
+
141
+ def _write_record(connection: sqlite3.Connection, envelope: Envelope) -> dict:
142
+ record_id = stable_id("record", envelope["scope"], envelope["recordKey"])
143
+ request_id = stable_id("request", envelope["scope"], envelope["requestId"])
144
+ input_digest = _digest(envelope)
145
+ previous = _replayed_request(connection, request_id, input_digest)
146
+ if previous is not None:
147
+ return previous
148
+ payload = _content_payload(envelope)
149
+ digest = _digest(payload)
150
+ existing = _source_revision(connection, record_id, envelope)
151
+ if existing is not None:
152
+ if existing[1] != digest:
153
+ raise DoyouknowError("source revision already holds different content")
154
+ if existing[2] != envelope["expectedPreviousRevision"]:
155
+ raise DoyouknowError("source revision has a different previous revision")
156
+ result = {"recordId": record_id, "revisionId": existing[0], "created": False}
157
+ else:
158
+ result = _append_revision(connection, envelope, record_id, payload, digest)
159
+ connection.execute(
160
+ "insert into request (id, input_digest, record_id, revision_id) values (?, ?, ?, ?)",
161
+ (request_id, input_digest, record_id, result["revisionId"]),
162
+ )
163
+ return result
164
+
165
+
166
+ def _replayed_request(
167
+ connection: sqlite3.Connection, request_id: str, digest: str,
168
+ ) -> dict | None:
169
+ row = connection.execute(
170
+ "select input_digest, record_id, revision_id from request where id = ?", (request_id,),
171
+ ).fetchone()
172
+ if row is None:
173
+ return None
174
+ if row[0] != digest:
175
+ raise DoyouknowError("request id already holds a different input")
176
+ return {"recordId": row[1], "revisionId": row[2], "created": False}
177
+
178
+
179
+ def _source_revision(
180
+ connection: sqlite3.Connection, record_id: str, envelope: Envelope,
181
+ ) -> tuple | None:
182
+ source = envelope["source"]
183
+ return connection.execute(
184
+ "select id, content_digest, previous_revision from revision where record_id = ? and source_kind = ? and source_id = ? and source_revision = ?",
185
+ (record_id, source["kind"], source["id"], source["revision"]),
186
+ ).fetchone()
187
+
188
+
189
+ def _append_revision(
190
+ connection: sqlite3.Connection, envelope: Envelope, record_id: str,
191
+ payload: dict, digest: str,
192
+ ) -> dict:
193
+ row = connection.execute("select latest_revision from record where id = ?", (record_id,)).fetchone()
194
+ previous = row[0] if row else None
195
+ if previous != envelope["expectedPreviousRevision"]:
196
+ raise DoyouknowError("record has a different latest revision")
197
+ _insert_node(connection, record_id, "record", envelope["scope"], envelope["recordKey"], envelope["record"]["title"])
198
+ connection.execute("insert into record (id) values (?) on conflict(id) do nothing", (record_id,))
199
+ revision_id = stable_id("revision", record_id, envelope["requestId"])
200
+ source = envelope["source"]
201
+ connection.execute(
202
+ "insert into revision (id, record_id, previous_revision, content_digest, source_kind, source_id, source_revision, created_at, payload) values (?, ?, ?, ?, ?, ?, ?, ?, ?)",
203
+ (revision_id, record_id, previous, digest, source["kind"], source["id"], source["revision"], datetime.now(timezone.utc).isoformat(), canonical_json(payload)),
204
+ )
205
+ _insert_graph(connection, envelope, record_id, revision_id)
206
+ connection.execute("update record set latest_revision = ? where id = ?", (revision_id, record_id))
207
+ return {"recordId": record_id, "revisionId": revision_id, "created": True}
208
+
209
+
210
+ def _insert_node(
211
+ connection: sqlite3.Connection, identity: str, kind: str, scope: str,
212
+ key: str, title: str,
213
+ ) -> None:
214
+ connection.execute(
215
+ "insert into node (id, kind, scope, canonical_key, title) values (?, ?, ?, ?, ?) on conflict(id) do nothing",
216
+ (identity, kind, scope, key, title),
217
+ )
218
+
219
+
220
+ def _insert_graph(
221
+ connection: sqlite3.Connection, envelope: Envelope, record_id: str,
222
+ revision_id: str,
223
+ ) -> None:
224
+ identities = {"$record": record_id}
225
+ for node in envelope["nodes"]:
226
+ identity = node_id(node)
227
+ _insert_node(connection, identity, node["kind"], node["scope"], node["key"], node["title"])
228
+ identities[node.get("ref", node["key"])] = identity
229
+ for index, relation in enumerate(envelope["relations"]):
230
+ connection.execute(
231
+ "insert into relation (id, revision_id, from_node, to_node, kind, reason, evidence, standing) values (?, ?, ?, ?, ?, ?, ?, ?)",
232
+ (stable_id("relation", revision_id, str(index)), revision_id, identities[relation["from"]], identities[relation["to"]], relation["kind"], relation["reason"], canonical_json(relation["evidence"]), relation["standing"]),
233
+ )
234
+
235
+
236
+ def show_record(record_id: str, *, home: Path | None = None) -> dict:
237
+ path = database_path(home)
238
+ _require_database_location(path)
239
+ if not path.is_file():
240
+ raise DoyouknowError("doyouknow record was not found")
241
+ try:
242
+ with closing(sqlite3.connect(path.as_uri() + "?mode=ro", uri=True, timeout=SQLITE_TIMEOUT_SECONDS)) as connection:
243
+ connection.execute("begin")
244
+ version = connection.execute("pragma user_version").fetchone()[0]
245
+ if version not in (1, SCHEMA_VERSION):
246
+ raise DoyouknowError(f"unsupported doyouknow database version: {version}")
247
+ return _read_record(connection, record_id, path)
248
+ except sqlite3.Error as exc:
249
+ raise DoyouknowError(f"doyouknow lookup failed: {exc}") from exc
250
+
251
+
252
+ def _read_record(connection: sqlite3.Connection, record_id: str, path: Path) -> dict:
253
+ record = connection.execute("select latest_revision from record where id = ?", (record_id,)).fetchone()
254
+ if record is None:
255
+ raise DoyouknowError("doyouknow record was not found")
256
+ rows = connection.execute(
257
+ "select id, previous_revision, created_at, payload from revision where record_id = ? order by rowid", (record_id,),
258
+ ).fetchall()
259
+ revisions = [{"revisionId": row[0], "previousRevision": row[1], "createdAt": row[2], **json.loads(row[3])} for row in rows]
260
+ return {"ok": True, "recordId": record_id, "revisionId": record[0], "revisions": revisions, "path": str(path)}
@@ -0,0 +1,58 @@
1
+ from __future__ import annotations
2
+
3
+ from collections.abc import Iterator
4
+ from functools import partial
5
+ from pathlib import Path
6
+
7
+ from ..json_boundary import JsonBoundaryError
8
+ from .config import SourceConfig, load_config
9
+ from .contracts import DoyouknowError
10
+ from .identity import stable_id
11
+ from .registration import retry_pending, validate_source_and_update_refusal_cache
12
+ from .source_contracts import SourceDomain, SourceKind, SourceScan
13
+ from .source_store import apply_source_scan
14
+ from .sources.manager import scan_managers
15
+ from .sources.memory import scan_memory_sources
16
+ from .sources.task import scan_project_tasks
17
+ from .store import database_path
18
+
19
+
20
+ def _source_scans(home: Path, settings: SourceConfig) -> Iterator[SourceScan]:
21
+ enabled = settings["sources"]
22
+ gate = partial(validate_source_and_update_refusal_cache, home=home)
23
+ if "memory" in enabled:
24
+ yield scan_memory_sources(home, settings, gate=gate)
25
+ if "manager" in enabled or "task" in enabled:
26
+ managers, projects = scan_managers(home, settings, gate=gate)
27
+ yield from managers
28
+ if "task" in enabled:
29
+ registry_unavailable = any(scan.status == "unavailable" for scan in managers)
30
+ for project_id, roots in sorted(projects.items()):
31
+ if registry_unavailable:
32
+ yield SourceScan(SourceDomain("task", project_id), (), (), "unavailable", ("project-registry-incomplete",))
33
+ elif len(roots) != 1:
34
+ yield SourceScan(SourceDomain("task", project_id), (), (), "unavailable", ("conflicting-project-roots",))
35
+ else:
36
+ yield scan_project_tasks(roots[0], project_id, settings)
37
+
38
+
39
+ def sync_sources(*, home: Path | None = None, source: SourceKind | None = None) -> dict:
40
+ root = database_path(home).parent.parent
41
+ settings = load_config(home=root)
42
+ if source is not None:
43
+ settings = {**settings, "sources": [source] if source in settings["sources"] else []}
44
+ pending = retry_pending(home=root, source=source, manual=True)
45
+ results = []
46
+ for scan in _source_scans(root, settings):
47
+ domain_id = stable_id("source-domain", scan.domain.kind, scan.domain.owner_id)
48
+ try:
49
+ if scan.domain.kind in settings["sources"]:
50
+ result = apply_source_scan(scan, home=root)
51
+ else:
52
+ result = {"status": scan.status, "registered": 0, "errors": list(scan.errors)}
53
+ except (DoyouknowError, JsonBoundaryError, OSError):
54
+ result = {"status": "unavailable", "registered": 0, "errors": ["source-registration-failed"]}
55
+ results.append({"kind": scan.domain.kind, "domainId": domain_id, **result})
56
+ return {"ok": pending["ok"] and not pending["truncated"] and all(row["status"] == "complete" for row in results),
57
+ "registered": sum(row["registered"] for row in results), "results": results,
58
+ "pendingRetry": pending}
@@ -263,7 +263,7 @@ class ExecutionMutationAudit:
263
263
  # Reported and, through `_retry_allowed`, load-bearing: a stat-cache
264
264
  # refresh must not read as "this worker touched Git" and must not
265
265
  # withhold the retry a worker that failed for another reason is owed.
266
- git_changed = _stable_git_projection(before) != _stable_git_projection(after)
266
+ git_changed = _git_projection_changed(before, after)
267
267
  violations = _policy_violations(
268
268
  before,
269
269
  after,
@@ -346,6 +346,9 @@ def _artifact_observation_roots(policies: Sequence[WritePolicy]) -> tuple[str, .
346
346
  roots: set[str] = set()
347
347
  for path in _allowed_artifact_paths(policies):
348
348
  parts = Path(path).parts
349
+ if parts[:3] == (".okstra", "agent-invocations", "code-review"):
350
+ roots.add(Path(*parts[:3]).as_posix())
351
+ continue
349
352
  if len(parts) < 5 or parts[:2] != (".okstra", "tasks"):
350
353
  continue
351
354
  if parts[4] == "qa":
@@ -808,6 +811,9 @@ def _git_projection(root: Path) -> dict[str, Any]:
808
811
  "gitDir": str(git_dir.resolve()),
809
812
  "gitCommonDir": str(common_dir.resolve()),
810
813
  "indexDigest": _optional_file_digest(index_path),
814
+ "indexContentDigest": "sha256:" + hashlib.sha256(
815
+ _git_output(root, "ls-files", "--stage", "-z").encode("utf-8")
816
+ ).hexdigest(),
811
817
  "stagedPaths": sorted(_git_changed_paths(root, "--cached")),
812
818
  "worktreeRegistration": _worktree_registration(root),
813
819
  "reflogDigest": _reflog_digest(root),
@@ -1032,7 +1038,7 @@ def _policy_violations(
1032
1038
  ) -> list[str]:
1033
1039
  if all(policy.source_mode == "source-readonly" for policy in policies):
1034
1040
  failures = ["readonly source changed"] if source_changes else []
1035
- if _stable_git_projection(before) != _stable_git_projection(after):
1041
+ if _git_projection_changed(before, after):
1036
1042
  failures.append("gitPolicy disabled but Git projection changed")
1037
1043
  return failures
1038
1044
  policy = next(row for row in policies if row.source_mode == "project-mutation")
@@ -1064,6 +1070,16 @@ def _stable_git_projection(snapshot: MutationSnapshot) -> dict[str, Any]:
1064
1070
  }
1065
1071
 
1066
1072
 
1073
+ def _git_projection_changed(before: MutationSnapshot, after: MutationSnapshot) -> bool:
1074
+ old = _stable_git_projection(before)
1075
+ current = _stable_git_projection(after)
1076
+ # Historical snapshots cannot establish the semantic index content they
1077
+ # did not capture. Preserve their original observation coverage on resume.
1078
+ if "indexContentDigest" not in old:
1079
+ current.pop("indexContentDigest", None)
1080
+ return old != current
1081
+
1082
+
1067
1083
  def _source_policy_failures(
1068
1084
  policy: WritePolicy,
1069
1085
  changed: set[str],