phronesis 1.0.0

package/vendor/core/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@phronesis/core",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Phronesis shared substrate — the ontology contract, workspace scan, link index, event log, and install-root discovery. Imported by every surface (CLI, daemon, GUI); imports from no app.",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "fs-extra": "^11.3.3",
+    "js-yaml": "^4.1.0",
+    "lunr": "^2.3.9"
+  },
+  "license": "MIT"
+}

package/vendor/core/src/action-registry.js

@@ -0,0 +1,459 @@
+// The action-type registry layer (core-0011 / T2.4; specs/ontology.md §"Action type
+// contract" :167; specs/trust-scopes.md Scope 1; per-packet decisions G1–G6 in
+// harness/tasks/core-0011-action-registry.md).
+//
+// T2.2 hardcoded the action-type table (schema + permission default + target layout)
+// in actions.js; this module externalizes it to the install's operator-editable
+// `.phronesis/registry.json` `action_types` section — WITHIN A SAFETY LATTICE WHOSE
+// FLOOR STAYS IN CODE. The split that matters:
+//
+//   code-resident (trusted baseline, compiled into @phronesis/core):
+//     handlers (prepare/build), newFileOnly, the approval FLOOR (`approvalFloor` on
+//     record_outcome / promote_to_codex), and the default table the scaffold section
+//     is GENERATED from (one source — scaffold and fallback cannot drift).
+//   registry-resident (operator-editable, validated against the floor at load):
+//     per-type input schema (the D2 field-spec shape, serialized verbatim as JSON —
+//     G2: no ajv), permission, target_layout, reserved per-action hook slots (the
+//     V1 executor consumes the top-level hooks array instead — core-0013 H1).
+//
+// Every function here is pure over its arguments (the code table is a parameter, the
+// bound convenience exports live in actions.js) — no disk, no install state.
+//
+// The lattice (G4/G5/G6):
+//   permission  auto-run < ask-once-if-new < requires-approval. Below an action's
+//               code floor → refuse at load (no escalation channel in V1). Non-floor
+//               actions may take any of the three values — the baseline is the FLOOR,
+//               not the default. Removing an entry unregisters the type (it refuses
+//               to run): removal is infinite tightening.
+//   schema      tighten-only: drop an optional field, narrow an enum, promote
+//               optional → required, add nonEmpty. Never: add a field the handler
+//               doesn't know (build() would silently drop it — the D2/null lesson),
+//               remove/un-require a required field, change a kind, widen an enum.
+//   layout      fixed contract in V1: must equal the code layout at load (canonical
+//               paths are what TYPE_DIR, export, and portability stand on); at run,
+//               the computed relPath must match the pattern — checked contract, not
+//               decoration.
+//
+// Failure policy (G3): an ABSENT action_types section means a pre-T2.4 registry —
+// the compiled defaults apply (safe: the fallback IS the code table, so absence can
+// never loosen anything). A PRESENT-but-invalid section fails closed ALL-OR-NOTHING:
+// one garbled entry disables the whole action layer with an error naming it. A config
+// error is loud and total, never partial.
+
+import { SLUG_SOURCE } from './contract.js';
+
+export const PERMISSION_ORDER = ['auto-run', 'ask-once-if-new', 'requires-approval'];
+
+// Strict top-level key set (G1): a typo'd section name (`action_type:`) must fail
+// closed, not silently restore defaults — the gate condition matches the invariant,
+// not "whatever parses". `review_intensity` is RESERVED, not consumed: the ratified
+// specs promise the operator the key in this file (trust-scopes.md Scope 2), so
+// strictness must not brick an install that follows the published spec — it sits
+// inert until its consumer (Scope 2 review surfaces) ships. `hooks` graduated from
+// that reserved class to CONSUMED in core-0013 (hook-executor.js resolveHooks —
+// hooks.md §"Hook registry format"); `skills` graduated in core-0015 (skill-registry.js
+// resolveSkillsSection — skills.md §"Skill registry"). Neither is validated HERE:
+// hooks and skills are separate failure domains with their own loaders.
+const REGISTRY_TOP_KEYS = [
+  'schema_version',
+  'created_by',
+  'domains',
+  'action_types',
+  'hooks',
+  'review_intensity',
+  'skills',
+];
+// Exported for the other registry-section loaders (skill-registry.js) — the known
+// version set is one source, never a re-typed copy that drifts. v2 landed with the
+// T5.1 compile handler (core-0017): the deferred-shaped v1 compile entry is rewritten
+// to the real handler shape and the version bumped, keyed on this field (H6 migration).
+export const REGISTRY_SCHEMA_VERSIONS = [0, 1, 2];
+
+// `note` is deliberately NOT an entry key: the per-type display annotation is
+// code-owned (status prints it from the code table). Serializing it would create a
+// field the loader validates-then-ignores — the silent intent-drop this module
+// refuses everywhere else.
+// `target_layout_by_object_type` is the compile handler's per-object_type layout map
+// (core-0017 H2b): compile writes two types (insight | organization) from one action,
+// so its canonical layout is a map keyed by the payload discriminator, not a single
+// string. Only the compile entry carries it; checkEntry refuses it elsewhere.
+const ENTRY_KEYS = [
+  'permission',
+  'target_layout',
+  'target_layout_by_object_type',
+  'schema',
+  'hooks',
+  'deferred_to',
+];
+const FIELD_SPEC_KEYS = ['kind', 'required', 'nonEmpty', 'values'];
+// `paths` (core-0017) is a list of install-relative source-path strings — the compile
+// handler's source_paths[]. It carries no nonEmpty/values/enum facets; required is the
+// only facet that applies (the list itself must be present and non-empty — enforced in
+// the handler's checkField, not as a per-element string facet).
+const FIELD_KINDS = ['string', 'slug', 'date', 'enum', 'links', 'paths'];
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+// Serialize one D2 field spec to its JSON-clean registry form: known keys only, enum
+// values copied (never a live reference into the code table).
+function serializeFieldSpec(spec) {
+  const out = { kind: spec.kind };
+  if (spec.required === true) out.required = true;
+  if (spec.nonEmpty === true) out.nonEmpty = true;
+  if (spec.values !== undefined) out.values = [...spec.values];
+  return out;
+}
+
+// The scaffold's action_types section, generated FROM the code table — the single
+// source the registry file is born from and the shape resolveActionTypes validates.
+export function buildActionTypesSection(codeTable) {
+  const section = {};
+  for (const [type, entry] of Object.entries(codeTable)) {
+    const out = { permission: entry.permission };
+    // A handler declares EITHER a single canonical layout or (compile, H2b) a
+    // per-object_type map — never both. The scaffold serializes whichever it holds.
+    if (entry.targetLayoutByObjectType) {
+      out.target_layout_by_object_type = { ...entry.targetLayoutByObjectType };
+    } else {
+      out.target_layout = entry.targetLayout;
+    }
+    if (entry.deferredTo) out.deferred_to = entry.deferredTo;
+    if (entry.schema) {
+      out.schema = {};
+      for (const [field, spec] of Object.entries(entry.schema)) {
+        out.schema[field] = serializeFieldSpec(spec);
+      }
+    }
+    // Per-action hook-binding slots: RESERVED, empty-only (core-0013 H1). The V1
+    // executor consumes the top-level `hooks` subscription array — a per-action
+    // binding is expressible as a subscription (action_type.requested/committed +
+    // a payload.action_type filter), so these slots have no consumer; a non-empty
+    // binding fails closed at load (a binding nothing honors is silent intent-drop).
+    out.hooks = { pre: [], post: [] };
+    section[type] = out;
+  }
+  return section;
+}
+
+// G5 — registry schemas are tighten-only against the code schema.
+function checkSchemaOverride(type, regSchema, codeSchema, errors) {
+  if (!isPlainObject(regSchema)) {
+    errors.push(`${type}.schema: must be an object of field specs`);
+    return;
+  }
+  for (const [field, spec] of Object.entries(regSchema)) {
+    // Own-property lookup, never the prototype chain: a field named `constructor`
+    // or `toString` must fail closed as unknown, not resolve to inherited junk.
+    if (!Object.hasOwn(codeSchema, field)) {
+      errors.push(
+        `${type}.schema.${field}: not a field the ${type} handler knows — the handler would silently drop it (add fields via a spec change, not the registry)`,
+      );
+      continue;
+    }
+    const code = codeSchema[field];
+    if (!isPlainObject(spec)) {
+      errors.push(`${type}.schema.${field}: must be a field-spec object`);
+      continue;
+    }
+    const unknown = Object.keys(spec).filter((k) => !FIELD_SPEC_KEYS.includes(k));
+    if (unknown.length) {
+      errors.push(`${type}.schema.${field}: unknown spec key(s): ${unknown.join(', ')}`);
+    }
+    if (!FIELD_KINDS.includes(spec.kind)) {
+      errors.push(`${type}.schema.${field}: kind "${spec.kind}" is not a D2 field kind (${FIELD_KINDS.join(' | ')})`);
+    } else if (spec.kind !== code.kind) {
+      errors.push(`${type}.schema.${field}: kind "${spec.kind}" differs from the handler's "${code.kind}" — kinds are not overridable`);
+    }
+    if (spec.required !== undefined && typeof spec.required !== 'boolean') {
+      errors.push(`${type}.schema.${field}: required must be a boolean`);
+    }
+    if (code.required === true && spec.required !== true) {
+      errors.push(`${type}.schema.${field}: the handler requires this field — required: true cannot be removed`);
+    }
+    if (spec.nonEmpty !== undefined && typeof spec.nonEmpty !== 'boolean') {
+      errors.push(`${type}.schema.${field}: nonEmpty must be a boolean`);
+    } else if (spec.nonEmpty === true && code.kind !== 'string') {
+      errors.push(`${type}.schema.${field}: nonEmpty only applies to string fields`);
+    }
+    if (code.nonEmpty === true && spec.nonEmpty !== true) {
+      errors.push(`${type}.schema.${field}: the handler refuses empty strings here — nonEmpty: true cannot be removed`);
+    }
+    if (code.kind === 'enum') {
+      if (!Array.isArray(spec.values) || spec.values.length === 0) {
+        errors.push(`${type}.schema.${field}: an enum field needs a non-empty values list`);
+      } else {
+        const widened = spec.values.filter((v) => !code.values.includes(v));
+        if (widened.length) {
+          errors.push(
+            `${type}.schema.${field}: values ${widened.join(', ')} are outside the handler's enum — enums may narrow, never widen`,
+          );
+        }
+      }
+    } else if (spec.values !== undefined) {
+      errors.push(`${type}.schema.${field}: values only applies to enum fields`);
+    }
+  }
+  for (const [field, code] of Object.entries(codeSchema)) {
+    if (code.required === true && regSchema[field] === undefined) {
+      errors.push(`${type}.schema: required field "${field}" is missing — the handler cannot run without it`);
+    }
+    // Dropping an OPTIONAL field is a legitimate tightening: payloads carrying it
+    // are then refused as unknown (fail closed), never silently accepted-and-ignored.
+  }
+}
+
+// G6 for compile's H2b map: the object_type set is fixed and each value must equal the
+// canonical layout. Binding the discriminator to the path here is what kills the
+// "registry pattern accepts a path the object_type contradicts" bug class the v3
+// alternation-string idea would have admitted (core-0017 H2b) — drift fails closed.
+function checkTargetLayoutMap(type, map, codeMap, errors) {
+  if (!isPlainObject(map)) {
+    errors.push(`${type}.target_layout_by_object_type: must be an object mapping object_type → canonical layout`);
+    return;
+  }
+  const codeKeys = Object.keys(codeMap).sort();
+  const regKeys = Object.keys(map).sort();
+  if (regKeys.join(',') !== codeKeys.join(',')) {
+    errors.push(
+      `${type}.target_layout_by_object_type: object_type set [${regKeys.join(', ') || '∅'}] differs from the canonical [${codeKeys.join(', ')}] — fixed contract`,
+    );
+    return;
+  }
+  for (const k of codeKeys) {
+    if (map[k] !== codeMap[k]) {
+      errors.push(
+        `${type}.target_layout_by_object_type.${k}: "${map[k]}" differs from the canonical layout "${codeMap[k]}" — layouts are fixed contract in V1`,
+      );
+    }
+  }
+}
+
+function checkHooks(type, hooks, errors) {
+  if (hooks === undefined) return;
+  if (!isPlainObject(hooks)) {
+    errors.push(`${type}.hooks: must be an object with pre/post lists`);
+    return;
+  }
+  const unknown = Object.keys(hooks).filter((k) => !['pre', 'post'].includes(k));
+  if (unknown.length) {
+    errors.push(`${type}.hooks: unknown key(s): ${unknown.join(', ')}`);
+  }
+  for (const phase of ['pre', 'post']) {
+    if (hooks[phase] === undefined) continue;
+    if (!Array.isArray(hooks[phase])) {
+      errors.push(`${type}.hooks.${phase}: must be a list`);
+    } else if (hooks[phase].length) {
+      errors.push(
+        `${type}.hooks.${phase}: per-action pre/post bindings have no consumer — the V1 executor reads the TOP-LEVEL hooks array (subscribe to action_type.requested/committed with a payload.action_type filter); a binding nothing honors is silent intent-drop`,
+      );
+    }
+  }
+}
+
+function checkEntry(type, entry, codeEntry, errors) {
+  if (!isPlainObject(entry)) {
+    errors.push(`${type}: must be an object`);
+    return;
+  }
+  const unknown = Object.keys(entry).filter((k) => !ENTRY_KEYS.includes(k));
+  if (unknown.length) {
+    errors.push(`${type}: unknown key(s): ${unknown.join(', ')}`);
+  }
+  // Layout is fixed contract in V1 (G6): relocating canonical state is a spec change,
+  // not a config flip — TYPE_DIR, the validator, and export all stand on these paths.
+  // compile (H2b) declares a per-object_type MAP instead of a single string; validate
+  // whichever the code table declares and refuse the wrong shape for this type.
+  if (codeEntry.targetLayoutByObjectType) {
+    if (entry.target_layout !== undefined) {
+      errors.push(
+        `${type}.target_layout: ${type} uses target_layout_by_object_type (a per-object_type map), not a single target_layout`,
+      );
+    }
+    checkTargetLayoutMap(type, entry.target_layout_by_object_type, codeEntry.targetLayoutByObjectType, errors);
+  } else {
+    if (entry.target_layout_by_object_type !== undefined) {
+      errors.push(
+        `${type}.target_layout_by_object_type: only the compile handler carries a per-object_type layout map`,
+      );
+    }
+    if (entry.target_layout !== codeEntry.targetLayout) {
+      errors.push(
+        `${type}.target_layout: "${entry.target_layout}" differs from the canonical layout "${codeEntry.targetLayout}" — layouts are fixed contract in V1`,
+      );
+    }
+  }
+  checkHooks(type, entry.hooks, errors);
+
+  if (codeEntry.deferredTo) {
+    // A deferred type (compile → T5.1) is registered but not runnable: its
+    // descriptive permission is recorded verbatim, never lattice-checked — the
+    // deferral refusal fires before any gate could read it.
+    if (typeof entry.permission !== 'string' || entry.permission.trim() === '') {
+      errors.push(`${type}.permission: must be a non-empty string`);
+    }
+    if (entry.deferred_to !== codeEntry.deferredTo) {
+      errors.push(`${type}.deferred_to: must be "${codeEntry.deferredTo}" (the handler is code-deferred)`);
+    }
+    if (entry.schema !== undefined) {
+      errors.push(`${type}.schema: a deferred type has no runnable schema yet`);
+    }
+    return;
+  }
+
+  if (entry.deferred_to !== undefined) {
+    errors.push(`${type}.deferred_to: only code-deferred types carry this (deferral is not operator-settable)`);
+  }
+  if (!PERMISSION_ORDER.includes(entry.permission)) {
+    errors.push(
+      `${type}.permission: "${entry.permission}" is not in the permission vocabulary (${PERMISSION_ORDER.join(' | ')})`,
+    );
+  } else if (
+    codeEntry.approvalFloor &&
+    PERMISSION_ORDER.indexOf(entry.permission) < PERMISSION_ORDER.indexOf('requires-approval')
+  ) {
+    // The lattice bite (G4): the comparison baseline is the CODE floor, never the
+    // registry's own prior value. Refused outright — no escalation channel in V1.
+    errors.push(
+      `${type}.permission: "${entry.permission}" loosens a code-floor approval-required action — the floor is compiled into @phronesis/core and is not registry-overridable`,
+    );
+  }
+  if (entry.schema === undefined) {
+    errors.push(`${type}.schema: required — the registry is what payloads validate against`);
+  } else {
+    checkSchemaOverride(type, entry.schema, codeEntry.schema, errors);
+  }
+}
+
+// Parse one registry field-spec back into the live D2 shape validatePayload consumes.
+// (Today the shapes coincide; the explicit pick keeps an extra registry key from ever
+// reaching checkField unvalidated.)
+function liveFieldSpec(spec) {
+  const out = { kind: spec.kind };
+  if (spec.required === true) out.required = true;
+  if (spec.nonEmpty === true) out.nonEmpty = true;
+  if (spec.values !== undefined) out.values = [...spec.values];
+  return out;
+}
+
+// Resolve the EFFECTIVE action-type table for one install: the registry's schema /
+// permission / layout over the code table's handlers. Returns:
+//   { errors, source, effective }
+//   errors     non-empty → the whole action layer is invalid (all-or-nothing, G3)
+//   source     'registry' (section present and valid) | 'defaults' (absent section)
+//   effective  type → { ...codeEntry, schema, permission, targetLayout } — a type
+//              whose entry was removed from a present section is ABSENT here
+//              (unregistered: it refuses to run; removal is infinite tightening)
+export function resolveActionTypesAgainst({ registry, codeTable }) {
+  const errors = [];
+  if (!isPlainObject(registry)) {
+    return { errors: ['.phronesis/registry.json must be a JSON object'], source: 'defaults', effective: {} };
+  }
+  const unknownTop = Object.keys(registry).filter((k) => !REGISTRY_TOP_KEYS.includes(k));
+  if (unknownTop.length) {
+    errors.push(
+      `unknown top-level key(s) in .phronesis/registry.json: ${unknownTop.join(', ')} (allowed: ${REGISTRY_TOP_KEYS.join(', ')})`,
+    );
+  }
+  // The version is READ, not just written: a future shape change (the T5.1 compile
+  // handler will obsolete today's deferred-shaped compile entry) keys its migration
+  // on this field — an unversionable config file makes every upgrade a surprise.
+  if (!REGISTRY_SCHEMA_VERSIONS.includes(registry.schema_version)) {
+    errors.push(
+      `schema_version "${registry.schema_version}" is not a known registry version (${REGISTRY_SCHEMA_VERSIONS.join(', ')})`,
+    );
+  }
+  // The domain list is part of what the action layer loads: every action's domain
+  // resolution depends on it, so a malformed list fails closed HERE — the one
+  // validator both `act` and `registry status` consume (a status that calls the
+  // layer disabled while act still writes is the two-matchers drift, rules.md).
+  if (!Array.isArray(registry.domains) || registry.domains.some((d) => typeof d !== 'string')) {
+    errors.push('domains: must be a list of domain-slug strings (every action resolves its domain against it)');
+  }
+
+  const section = registry.action_types;
+  // A section under schema_version 0 is contradictory state: version 0 predates the
+  // section, and the version field is what future migrations key on (the T5.1
+  // obligation) — v1-shaped content under v0 would make that keying meaningless.
+  if (section !== undefined && registry.schema_version === 0) {
+    errors.push(
+      'action_types requires schema_version 1 — a version-0 registry predates the section (bump the version, or remove the section to keep built-in defaults)',
+    );
+  }
+  if (section === undefined) {
+    // Pre-T2.4 registry (G3): compiled defaults. Safe — the fallback IS the code
+    // table, so an absent section can never loosen anything.
+    return { errors, source: 'defaults', effective: errors.length ? {} : { ...codeTable } };
+  }
+
+  if (!isPlainObject(section)) {
+    errors.push('action_types: must be an object mapping type → entry');
+    return { errors, source: 'registry', effective: {} };
+  }
+  // core-0017 H6 — fail closed RECOVERABLY when the compile handler has landed (the code
+  // table's compile is no longer deferred) but this install still carries the pre-T5.1
+  // deferred-shaped compile entry. Without this, that stale entry fails every
+  // non-deferred check at once (a descriptive permission, no schema, a deferred_to the
+  // code no longer declares) and disables the WHOLE action layer on a routine
+  // @phronesis/core upgrade. One recoverable instruction beats the generic error wall.
+  if (
+    isPlainObject(section.compile) &&
+    section.compile.deferred_to !== undefined &&
+    codeTable.compile &&
+    !codeTable.compile.deferredTo
+  ) {
+    errors.push(
+      'action_types.compile is the pre-T5.1 deferred entry, but the compile handler has landed — run the compile-handler migration (`node harness/migrations/0017-compile-handler.mjs <install>`) to rewrite it to the real schema and bump schema_version to 2',
+    );
+    return { errors, source: 'registry', effective: {} };
+  }
+  for (const type of Object.keys(section)) {
+    // Own-property lookup (an entry named `constructor`/`toString` must hit this
+    // refusal, not resolve up the prototype chain and skip validation entirely).
+    if (!Object.hasOwn(codeTable, type)) {
+      errors.push(
+        `action_types.${type}: no such action type in @phronesis/core — a registry entry cannot conjure a handler (Action Sprawl stays resisted)`,
+      );
+    }
+  }
+  const effective = {};
+  for (const [type, codeEntry] of Object.entries(codeTable)) {
+    const entry = section[type];
+    if (entry === undefined) continue; // unregistered — refuses to run
+    checkEntry(type, entry, codeEntry, errors);
+    if (errors.length) continue; // shape only matters when everything is valid
+    const merged = { ...codeEntry, permission: entry.permission };
+    if (codeEntry.targetLayoutByObjectType) {
+      merged.targetLayoutByObjectType = { ...entry.target_layout_by_object_type };
+    } else {
+      merged.targetLayout = entry.target_layout;
+    }
+    if (entry.schema !== undefined) {
+      merged.schema = {};
+      for (const [field, spec] of Object.entries(entry.schema)) {
+        merged.schema[field] = liveFieldSpec(spec);
+      }
+    }
+    effective[type] = merged;
+  }
+  if (errors.length) return { errors, source: 'registry', effective: {} };
+  return { errors, source: 'registry', effective };
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Compile a target_layout into the pattern the computed relPath must match (G6 —
+// checked contract, not decoration): {domain} is the RESOLVED domain literal,
+// {slug}/{name} are the one slug grammar (contract.js — never a re-typed copy),
+// YYYY-MM-DD is a date stamp.
+export function layoutPattern(layout, { domain }) {
+  const re = escapeRegExp(layout)
+    .replaceAll('\\{domain\\}', escapeRegExp(domain))
+    .replaceAll('\\{slug\\}', SLUG_SOURCE)
+    .replaceAll('\\{name\\}', SLUG_SOURCE)
+    .replaceAll('YYYY-MM-DD', '\\d{4}-\\d{2}-\\d{2}');
+  return new RegExp(`^${re}$`);
+}