@quolu/lattice 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Lattice — phase-aware TODO graph compiler and conflict-aware orchestration runtime",
   "type": "module",
   "license": "MIT",

package/src/boundary-observation-compiler-v2.mjs

@@ -15,6 +15,11 @@ const PROVENANCE_SOURCES = new Set([
 const SENSOR_STATUSES = new Set([
   'ready',
   'symbol_absent',
+  // 不存在path関連。宣言の有無で3つに分かれる（ADR 0136）。宣言が無いabsentはpath_absent、
+  // 宣言があるのに実在するのはcreates_path_present、fs観測が記録に無いのはcreates_unverified。
+  'path_absent',
+  'creates_path_present',
+  'creates_unverified',
   'empty',
   'unresolved',
   'command_failure',

package/src/runtime-contracts.mjs

@@ -140,10 +140,23 @@ const STATE_EFFECT_KINDS = Object.freeze([
   'external_effect',
 ]);
 
-function ownEntry(value) {
-  return plainObject(value)
-    && exactRecord(value, ['kind', 'target'])
+/**
+ * 所有宣言。`creates: true`は「このpathはまだ存在せず、このTODOが作る」という創作の意思である
+ * （ADR 0135 Decision 3・ADR 0136）。
+ *
+ * `kind`は`path`のまま据え置く。存在の有無は資源の種類ではなく資源の状態であり、kindを分けると
+ * 既存のpath判定（write交差の免除、conflict resourceのkind）が全部この宣言を取りこぼす。
+ *
+ * 値は`true`だけを受理する。`false`は「存在するpath」と同義で、同じ事実に2つの書き方を
+ * 与えることになる。省略が既定である。
+ */
+function ownEntry(value, { allowCreates = false } = {}) {
+  if (!plainObject(value)) return false;
+  const creates = Object.hasOwn(value, 'creates');
+  if (creates && !allowCreates) return false;
+  return exactRecord(value, creates ? ['kind', 'target', 'creates'] : ['kind', 'target'])
     && OWN_KINDS.includes(value.kind)
+    && (!creates || (value.creates === true && value.kind === 'path'))
     && typeof value.target === 'string'
     && value.target.length > 0
     && Buffer.byteLength(value.target, 'utf8') <= MAX_PATH_BYTES;
@@ -221,6 +234,17 @@ const WITNESS_PROVENANCE = Object.freeze([
   'manual_state_effect',
 ]);
 
+/**
+ * 現行のrun request契約。v2は`owns[].creates`だけがv1との差であり、境界宣言としては同値である。
+ * 既存requestの書き換えを要求しないため、v1は読み口として残す。
+ */
+export const RUN_REQUEST_SCHEMA = 'lattice.run_request.v2';
+export const RUN_REQUEST_LEGACY_SCHEMAS = Object.freeze(['lattice.run_request.v1']);
+export const RUN_REQUEST_SCHEMAS = Object.freeze([
+  RUN_REQUEST_SCHEMA,
+  ...RUN_REQUEST_LEGACY_SCHEMAS,
+]);
+
 export const RUN_REQUEST_FIELDS = Object.freeze([
   'schema',
   'request_id',
@@ -276,7 +300,9 @@ export function explainRunRequest(value) {
     return reject('non_canonical_request_bytes', '');
   }
   if (!exactRecord(value, RUN_REQUEST_FIELDS)) return reject('unexpected_or_missing_top_level_keys', '');
-  if (value.schema !== 'lattice.run_request.v1') return reject('schema_mismatch', '/schema');
+  if (!RUN_REQUEST_SCHEMAS.includes(value.schema)) return reject('schema_mismatch', '/schema');
+  // 創作宣言はv2から。v1のclosed shapeは余分fieldを拒否するので加算互換が成立しない。
+  const allowCreates = value.schema === RUN_REQUEST_SCHEMA;
   if (!identifier(value.request_id)) return reject('invalid_identifier', '/request_id');
   if (!exactRecord(value.repo, ['base_sha', 'root_kind'])) return reject('unexpected_or_missing_keys', '/repo');
   if (!gitSha(value.repo.base_sha)) return reject('invalid_git_sha', '/repo/base_sha');
@@ -301,7 +327,9 @@ export function explainRunRequest(value) {
     const at = `/manual_witness/${todoId}`;
     if (!plainObject(witness)) return reject('not_an_object', at);
     if (!exactRecord(witness, MANUAL_WITNESS_FIELDS)) return reject('unexpected_or_missing_keys', at);
-    if (!boundedArray(witness.owns, ownEntry)) return reject('invalid_own_entries', `${at}/owns`);
+    if (!boundedArray(witness.owns, (own) => ownEntry(own, { allowCreates }))) {
+      return reject('invalid_own_entries', `${at}/owns`);
+    }
     if (!repoPathArray(witness.reads)) return reject('invalid_repo_relative_paths', `${at}/reads`);
     if (!repoPathArray(witness.writes, { allowPrefix: true })) return reject('invalid_repo_relative_paths', `${at}/writes`);
     if (!boundedArray(witness.resources, identifier)) return reject('invalid_identifier', `${at}/resources`);
@@ -371,7 +399,18 @@ export function verifyRuntimePlanBinding(options = {}) {
   return plan.nodes.every((node) => requestTodoIds.has(node.todo_id));
 }
 
-/** `lattice.boundary_manifest.v2`。witness_provenanceはresourceごとに区別する。 */
+/**
+ * `lattice.boundary_manifest.v3`。witness_provenanceはresourceごとに区別する。
+ *
+ * v3は`owns[].creates`だけがv2との差である。宣言が持っていた「このpathはまだ無い」を
+ * 記録側でも保つ——落とすと、manifestだけを読む消費者が既存fileと同じ扱いをする。
+ * 旧v2 manifestはrun storeに残るので読み口として受理する。
+ */
+export const BOUNDARY_MANIFEST_SCHEMA = 'lattice.boundary_manifest.v3';
+export const BOUNDARY_MANIFEST_SCHEMAS = Object.freeze([
+  BOUNDARY_MANIFEST_SCHEMA,
+  'lattice.boundary_manifest.v2',
+]);
 export function validateRuntimeBoundaryManifest(value) {
   return validateSafely(value, (manifest) => (
     exactRecord(manifest, [
@@ -388,9 +427,11 @@ export function validateRuntimeBoundaryManifest(value) {
       'witness_provenance',
       'manifest_digest',
     ])
-    && manifest.schema === 'lattice.boundary_manifest.v2'
+    && BOUNDARY_MANIFEST_SCHEMAS.includes(manifest.schema)
     && identifier(manifest.todo_id)
-    && boundedArray(manifest.owns, ownEntry)
+    && boundedArray(manifest.owns, (own) => ownEntry(own, {
+      allowCreates: manifest.schema === BOUNDARY_MANIFEST_SCHEMA,
+    }))
     && repoPathArray(manifest.reads)
     && repoPathArray(manifest.writes, { allowPrefix: true })
     && boundedArray(manifest.resources, identifier)

package/src/runtime-front-end.mjs

@@ -6,6 +6,7 @@ import { portableSensorOutcome } from './sensor-adapter.mjs';
 import { compileSchedulabilityGraphV2 } from './schedulability-compiler-v2.mjs';
 import { verifySchedulabilityPlanV2 } from './schedulability-verifier-v2.mjs';
 import {
+  BOUNDARY_MANIFEST_SCHEMA,
   SENSOR_EXPECT_KINDS,
   SENSOR_QUERY_OPERATIONS,
   selfDigest,
@@ -265,11 +266,44 @@ function entryNode(entry) {
   return null;
 }
 
+/**
+ * 創作宣言されたpathの裏付けを決める（ADR 0136）。
+ *
+ * 宣言と観測が一致する時だけ`ready`にする。fresh absentは推測ではなくfsのlstat結果なので、
+ * 「観測できなかった」ではなく「観測して、無かった」である。存在しないfileに依存するものは
+ * 構造的に存在しえないため、affected testが空であることまで確かめれば裏付けは閉じる。
+ *
+ * 既に存在するpathへ創作を宣言していたら`creates_path_present`で止める。実害は無いが、
+ * 宣言が実態からずれているのを黙って通すと、宣言と観測が一致しているという前提が崩れる。
+ * 宣言していないabsent pathは従来どおり`path_absent`のままにする——綴り違いを
+ * 「黙って通る創作境界」にしないための線である。
+ */
+function creationBoundaryStatus(outcome, expectPath) {
+  // sensorが答えられていない状況は、この関数の管轄でない。通常のstatus判定へ返す。
+  if (!['ready', 'empty'].includes(outcome.status)) return null;
+  const target = affectedTarget(outcome.raw, expectPath);
+  // fs観測が記録に無いなら、不存在は確かめられていない。宣言だけで裏付けにしない。
+  if (target === null || target === undefined) return 'creates_unverified';
+  if (target.path_state !== 'absent') return 'creates_path_present';
+  const payload = affectedPayload(outcome.raw, expectPath);
+  if (payload === null
+    || !Array.isArray(payload.changedFiles)
+    || payload.changedFiles.length !== 1
+    || payload.changedFiles[0] !== expectPath
+    || !Array.isArray(payload.affectedTests)
+    || payload.affectedTests.length !== 0) return 'creates_unverified';
+  return 'ready';
+}
+
 /**
  * 束縛queryのoutcomeへexpectをexact照合し、sensor statusを決める。
  * fuzzy解決・空結果は依存なしへ丸めず、unknown系statusへ落とす（AGENTS.md）。
  */
 function resolveBindingStatus(binding, outcome) {
+  if (binding.expect.kind === 'affected' && binding.creates === true) {
+    const declared = creationBoundaryStatus(outcome, binding.expect.path);
+    if (declared !== null) return declared;
+  }
   if (outcome.status !== 'ready') return outcome.status;
   const { expect } = binding;
   if (expect.kind === 'affected') {
@@ -401,7 +435,13 @@ export function compileRuntimePlanV1(options = {}) {
   const driftDetails = [];
   for (const todoId of todoIds) {
     const witness = request.manual_witness[todoId];
-    const bindings = normalizeProvenanceQueries(witness, todoId);
+    // 創作宣言はowns側にある。裏付けを決めるのはbindingなので、覆っているbindingへ写す。
+    const creating = new Set(witness.owns
+      .filter((own) => own.creates === true).map((own) => own.target));
+    const bindings = normalizeProvenanceQueries(witness, todoId)
+      .map((binding) => (creating.size > 0
+        && [...creating].some((target) => bindingCoversOwn(binding, { kind: 'path', target }))
+        ? { ...binding, creates: true } : binding));
     for (const binding of bindings) {
       const query = queryById.get(binding.query_id);
       if (query === undefined) {
@@ -697,7 +737,7 @@ export function compileRuntimePlanV1(options = {}) {
       guidance: hasFreshAbsentPath
         ? {
           code: 'BOOTSTRAP_OWNERSHIP_SEAM',
-          message: 'fresh path観測で不存在の新規pathは親が空の専用seamをbase commitへ先行追加し、sensor sync後に同じrequestを再compileする',
+          message: '不存在と観測されたpathは、そのTODOが作るならowns entryへcreates: trueを宣言して再compileする。宣言せずに裏付けを得るなら、親が空の専用seamをbase commitへ先行追加し、sensor sync後に同じrequestを再compileする',
         }
         : {
           code: 'ACQUIRE_OWNERSHIP_EVIDENCE',
@@ -729,7 +769,7 @@ export function compileRuntimePlanV1(options = {}) {
         : 'manual_state_effect';
     }
     const manifest = {
-      schema: 'lattice.boundary_manifest.v2',
+      schema: BOUNDARY_MANIFEST_SCHEMA,
       todo_id: todoId,
       owns: witness.owns,
       reads: witness.reads,
@@ -751,7 +791,7 @@ export function compileRuntimePlanV1(options = {}) {
     };
     manifest.manifest_digest = selfDigest(manifest, 'manifest_digest');
     if (!validateRuntimeBoundaryManifest(manifest)) {
-      fail(`生成manifestがboundary_manifest.v2 contractを満たさない: ${todoId}`);
+      fail(`生成manifestがboundary_manifest contractを満たさない: ${todoId}`);
     }
     manifests[todoId] = manifest;
   }

package/src/todo-independence-contracts.mjs

@@ -8,21 +8,31 @@ import {
 } from './todo-contracts.mjs';
 import {
   RUN_REQUEST_CLAIM_MODE,
+  RUN_REQUEST_SCHEMA,
   explainRunRequest,
   selfDigest as runtimeSelfDigest,
 } from './runtime-contracts.mjs';
 import { TODO_INDEPENDENCE_GUIDANCE_CODES } from './todo-independence-guidance.mjs';
 
-export const TODO_WITNESS_SET_SCHEMA = 'lattice.todo_witness_set.v2';
+export const TODO_WITNESS_SET_SCHEMA = 'lattice.todo_witness_set.v3';
 /**
- * まだ受理する旧witness set契約。v1はconcern anchorを持てないだけで、境界宣言としては
- * v2と同値である。既存宣言を書き換えさせないために読み口を残す。
+ * まだ受理する旧witness set契約。v1はconcern anchorを、v2は創作宣言を持てないだけで、
+ * 境界宣言としてはv3と同値である。既存宣言を書き換えさせないために読み口を残す。
  */
-export const TODO_WITNESS_SET_LEGACY_SCHEMAS = Object.freeze(['lattice.todo_witness_set.v1']);
+export const TODO_WITNESS_SET_LEGACY_SCHEMAS = Object.freeze([
+  'lattice.todo_witness_set.v2',
+  'lattice.todo_witness_set.v1',
+]);
 export const TODO_WITNESS_SET_SCHEMAS = Object.freeze([
   TODO_WITNESS_SET_SCHEMA,
   ...TODO_WITNESS_SET_LEGACY_SCHEMAS,
 ]);
+/** 宣言できる欄はversionごとに違う。どの版から使えるかを1箇所で持つ。 */
+const CONCERN_ANCHOR_SCHEMAS = Object.freeze([
+  TODO_WITNESS_SET_SCHEMA,
+  'lattice.todo_witness_set.v2',
+]);
+const CREATES_SCHEMAS = Object.freeze([TODO_WITNESS_SET_SCHEMA]);
 
 /** 1 taskが宣言できるconcern anchorの資源数と、資源あたりのsymbol数の上限。 */
 export const TODO_CONCERN_ANCHOR_LIMIT = 256;
@@ -117,7 +127,7 @@ function boundedText(value, maximumBytes = 4_096) {
 export function synthesizeWitnessRunRequest(witnessSet, { baseSha, requestId }) {
   const taskIds = Object.keys(witnessSet.manual_witness).sort(compareText);
   const request = {
-    schema: 'lattice.run_request.v1',
+    schema: RUN_REQUEST_SCHEMA,
     request_id: requestId,
     repo: { base_sha: baseSha, root_kind: 'git' },
     capacity: witnessSet.capacity,
@@ -212,13 +222,19 @@ export function explainTodoWitnessSet(value) {
     });
     const explained = explainRunRequest(probe);
     if (!explained.valid) return reject(explained.reason, explained.path);
-    // concern anchorはprobeへ写していないので、ここが唯一の判定正本になる。
-    const legacy = TODO_WITNESS_SET_LEGACY_SCHEMAS.includes(value.schema);
+    // 版ごとの欄。probeはRUN_REQUEST_SCHEMAで合成するので創作宣言はそこを通ってしまう。
+    // 旧版の宣言に新しい欄を書けないことは、ここだけが見る。
     for (const taskId of taskIds) {
       const witness = value.manual_witness[taskId];
+      if (!CREATES_SCHEMAS.includes(value.schema)
+        && witness.owns.some((own) => Object.hasOwn(own, 'creates'))) {
+        return reject('creates_require_witness_set_v3', `/manual_witness/${taskId}/owns`);
+      }
       const at = `/manual_witness/${taskId}/concern_anchors`;
       if (!Object.hasOwn(witness, 'concern_anchors')) continue;
-      if (legacy) return reject('concern_anchors_require_witness_set_v2', at);
+      if (!CONCERN_ANCHOR_SCHEMAS.includes(value.schema)) {
+        return reject('concern_anchors_require_witness_set_v2', at);
+      }
       const anchors = explainConcernAnchors(witness.concern_anchors, witness.owns, at);
       if (!anchors.valid) return reject(anchors.reason, anchors.path);
     }