@event4u/agent-config 17.3.0 → 17.4.0

package/src/scripts/schemas/provenance-mechanism.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "provenance-mechanism.schema.json",
+  "title": "Provenance ledger mechanism decision",
+  "description": "One line of provenance/mechanisms.jsonl — a decision about one harvested mechanism: adopted, adapted, rejected, already present, missing, or deferred. Source-free by construction (council O5): no source id, no pin, no locator. What links a source to a mechanism lives in the local ledger under the user-global runtime/lineage/ and never in the tracked tree. Append-only; a later row for the same mechanism_id supersedes an earlier one. Contract: provenance/README.md. Enforced by src/scripts/lint_harvest_provenance.ts.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["mechanism_id", "verdict", "decided_at"],
+  "properties": {
+    "mechanism_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "description": "Kebab-case slug naming the mechanism. A harvest citation marker may cite it; for a mechanism seeded from harvests.jsonl it equals the harvest_id."
+    },
+    "verdict": {
+      "type": "string",
+      "enum": ["adopt", "adapt", "reject", "already", "gap", "deferred"],
+      "description": "adopt|adapt — realised in this repo; reject — decided against; already — present before the harvest; gap — wanted and missing; deferred — wanted, parked."
+    },
+    "realised_in": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" },
+      "description": "Repo-relative paths where the mechanism lives, each optionally suffixed ':<line>'. Required for adopt and adapt; every path must exist."
+    },
+    "roadmap": {
+      "type": "string",
+      "description": "Repo-relative path of the roadmap that owns a gap or deferred mechanism, or the literal 'open' when nothing owns it yet."
+    },
+    "decided_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO-8601 date (YYYY-MM-DD) of the decision."
+    },
+    "reason": {
+      "type": "string",
+      "minLength": 3,
+      "description": "Why. Required for reject."
+    },
+    "reopen_if": {
+      "type": "string",
+      "minLength": 3,
+      "description": "The condition under which a rejection or deferral is reconsidered."
+    }
+  }
+}

package/src/scripts/update_notice_hook.ts

@@ -32,6 +32,7 @@
  * It is fail-open on every path and returns 0 on every path, including an
  * unreadable state file, an unwritable state directory and a missing changelog.
  */
+import { randomUUID } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -48,6 +49,7 @@ import { parse_version } from './_lib/version_order.js';
 import * as user_global_paths from './_lib/user_global_paths.js';
 import { readHookStdin } from './hooks/hook_stdin.js';
 import { is_replay_mode } from './hooks/state_io.js';
+import { hostShowsUserNotice, readNoticeReceipt, USER_NOTICE_ID_KEY, USER_NOTICE_KEY, type NoticeReceipt } from './hooks/user_notice.js';
 
 export const CONCERN = 'update-notice';
 export const NOTICE_STATE_FILENAME = 'update-notice.json';
@@ -73,6 +75,15 @@ export const NOTICE_STATE_SCHEMA = 1;
 export interface NoticeState {
     readonly staged: string | null;
     readonly last_seen_installed: string | null;
+    /**
+     * A notice handed to the dispatcher's user channel and not yet confirmed:
+     * the session it was handed over in, the id it was handed over with, and the
+     * installed version it reported. It becomes `last_seen_installed` only when
+     * the dispatcher's receipt names that session AND that id
+     * (`hooks/user_notice.ts`) — an older receipt from the same session is a
+     * receipt for another notice. Until then the notice is due again.
+     */
+    readonly pending?: { readonly session_id: string; readonly notice_id: string; readonly installed: string };
 }
 
 export function readNoticeState(statePath: string | null): NoticeState {
@@ -82,12 +93,25 @@ export function readNoticeState(statePath: string | null): NoticeState {
         const o = raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, unknown>) : {};
         if (o['schema'] !== undefined && o['schema'] !== NOTICE_STATE_SCHEMA) return { staged: null, last_seen_installed: null };
         const str = (v: unknown): string | null => (typeof v === 'string' && parse_version(v.trim()) !== null ? v.trim() : null);
-        return { staged: str(o['staged']), last_seen_installed: str(o['last_seen_installed']) };
+        const p = o['pending'] as Record<string, unknown> | null | undefined;
+        const installed = str(p?.['installed']);
+        const pending =
+            typeof p?.['session_id'] === 'string' && typeof p['notice_id'] === 'string' && installed !== null
+                ? { session_id: p['session_id'], notice_id: p['notice_id'], installed }
+                : undefined;
+        return { staged: str(o['staged']), last_seen_installed: str(o['last_seen_installed']), ...(pending ? { pending } : {}) };
     } catch {
         return { staged: null, last_seen_installed: null };
     }
 }
 
+/** The state with a pending notice promoted, when the dispatcher's receipt names its session and its id. */
+export function confirmDelivered(state: NoticeState, receipt: NoticeReceipt | null): NoticeState {
+    const p = state.pending;
+    if (p === undefined || receipt === null || !receipt.notice_id || receipt.notice_id !== p.notice_id || receipt.session_id !== p.session_id) return state;
+    return { staged: state.staged, last_seen_installed: p.installed };
+}
+
 export function writeNoticeState(statePath: string, state: NoticeState): void {
     try {
         write_atomic(statePath, `${JSON.stringify({ schema: NOTICE_STATE_SCHEMA, ...state }, null, 2)}\n`);
@@ -138,11 +162,11 @@ function readText(p: string): string {
     }
 }
 
-function sessionIdFromEnvelope(raw: string): string | null {
+function envelopeField(raw: string, key: string): string | null {
     try {
         const doc: unknown = JSON.parse(raw);
-        const id = (doc as Record<string, unknown> | null)?.['session_id'];
-        return typeof id === 'string' && id.trim() !== '' ? id.trim() : null;
+        const value = (doc as Record<string, unknown> | null)?.[key];
+        return typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
     } catch {
         return null;
     }
@@ -160,6 +184,14 @@ export interface NoticeDeps {
     readonly throttlePath: string;
     readonly registerDir: string;
     readonly err: { write(text: string): void };
+    /**
+     * The dispatcher's user channel (`hooks/user_notice.ts`), set only when the
+     * host shows a notice to the user. The lines then go there as one reply and
+     * nothing goes to stderr, which every host discards.
+     */
+    readonly notice?: { write(text: string): void };
+    /** The dispatcher's delivery receipt for this concern, read only on the `notice` path. */
+    readonly receipt?: () => NoticeReceipt | null;
 }
 
 /**
@@ -173,7 +205,7 @@ export function runNotice(deps: NoticeDeps, apply = true): NoticeOutcome {
 
     const probe = deps.probeStatePath === null ? {} : readJson(deps.probeStatePath);
     const seen = probe['last_seen_version'];
-    const state = readNoticeState(deps.noticeStatePath);
+    const state = confirmDelivered(readNoticeState(deps.noticeStatePath), deps.receipt?.() ?? null);
 
     const outcome = updateNotice({
         installed,
@@ -200,6 +232,23 @@ export function runNotice(deps: NoticeDeps, apply = true): NoticeOutcome {
         return outcome;
     }
 
+    // Through the host, a notice counts as shown only once the dispatcher's
+    // receipt names this session and this notice's id; until then it stays
+    // pending and is said again.
+    if (deps.notice !== undefined) {
+        const noticeId = randomUUID();
+        if (outcome.lines.length > 0) {
+            deps.notice.write(JSON.stringify({ [USER_NOTICE_KEY]: outcome.lines.join('\n'), [USER_NOTICE_ID_KEY]: noticeId }));
+        }
+        writeNoticeState(deps.noticeStatePath, {
+            staged: outcome.stage,
+            last_seen_installed: state.last_seen_installed,
+            ...(outcome.lines.length > 0 && deps.sessionId
+                ? { pending: { session_id: deps.sessionId, notice_id: noticeId, installed } }
+                : {}),
+        });
+        return outcome;
+    }
     for (const line of outcome.lines) deps.err.write(`[update] ${line}\n`);
     writeNoticeState(deps.noticeStatePath, { staged: outcome.stage, last_seen_installed: installed });
     return outcome;
@@ -214,6 +263,19 @@ export function runNotice(deps: NoticeDeps, apply = true): NoticeOutcome {
 export function noticeOncePerDay(deps: NoticeDeps): NoticeOutcome | null {
     const dry = runNotice(deps, false);
     if (dry.suppressed !== null && !RECONCILE_REASONS.has(dry.suppressed)) return null;
+    if (deps.notice !== undefined) {
+        // Through the host the day throttle is a DELIVERED notice today, so a
+        // notice the dispatcher dropped is said again at the next session.
+        const receipt = deps.receipt?.() ?? null;
+        if (receipt !== null && localDay(new Date(receipt.at)) === localDay(new Date())) {
+            const stored = readNoticeState(deps.noticeStatePath);
+            const confirmed = confirmDelivered(stored, receipt);
+            if (confirmed !== stored) writeNoticeState(deps.noticeStatePath, confirmed);
+            // Another session's receipt never throttles a notice still pending.
+            if (confirmed.pending === undefined) return null;
+        }
+        return runNotice(deps);
+    }
     if (ranToday(deps.throttlePath)) return null;
     const outcome = runNotice(deps);
     stampToday(deps.throttlePath);
@@ -261,11 +323,17 @@ export function main(argv?: string[]): number {
         // The throttle stamp is a WRITE, so it comes after the decision that
         // this context may be written in at all — AC-2 asks for zero writes
         // under CI, a non-TTY, a source checkout and the opt-out.
+        // Every host runs this on pipes, so a TTY says nothing about whether the
+        // user will see the notice; a host with a verified user channel does.
+        // Through the host a notice is confirmed by a receipt naming its session,
+        // so without a session id there is nothing to confirm it by: say nothing.
+        const viaHost = envelopeField(raw, 'session_id') !== null && hostShowsUserNotice(envelopeField(raw, 'platform'));
         const deps: NoticeDeps = {
             packageRoot,
-            sessionId: sessionIdFromEnvelope(raw),
+            sessionId: envelopeField(raw, 'session_id'),
             env: process.env,
-            isTty: Boolean(process.stderr.isTTY) || Boolean(process.stdout.isTTY),
+            isTty: viaHost || Boolean(process.stderr.isTTY) || Boolean(process.stdout.isTTY),
+            ...(viaHost ? { notice: process.stdout, receipt: () => readNoticeReceipt(CONCERN) } : {}),
             mode,
             probeStatePath: user_global_paths.resolve_with_fallback(STATE_FILENAME),
             noticeStatePath: user_global_paths.write_target(NOTICE_STATE_FILENAME),

package/src/vendor/grammars/README.md

@@ -10,9 +10,9 @@ with no manual parser install (ADR-259).
 
 `tree-sitter-wasms` carries 36 grammars (49 MiB on disk). Depending on it at
 runtime would hand every consumer all 36, which is the option ADR-259 §
-Alternatives rejects on exactly that measurement. Only the seven grammars below
+Alternatives rejects on exactly that measurement. Only the eight grammars below
 are loadable by the engine — `GRAMMAR_WASM` in `src/scripts/code_graph/types.ts`
-has seven entries — so the other 29 would be payload with no reader. Vue needs no
+has eight entries — so the other 28 would be payload with no reader. Vue needs no
 grammar of its own: the extractor blanks a component's template and parses its
 `<script>` with the TypeScript grammar.
 
@@ -30,8 +30,9 @@ the tarball; the loader reads them from disk.
 | go | `tree-sitter-go.wasm` | `9963ca89b616eaf04b08a43bc1fb0f07b85395bec313330851f1f1ead2f755b6` |
 | java | `tree-sitter-java.wasm` | `637aac4415fb39a211a4f4292d63c66b5ce9c32fa2cd35464af4f681d91b9a1f` |
 | csharp | `tree-sitter-c_sharp.wasm` | `6266a7e32d68a3459104d994dc848df15d5672b0ea8e86d327274b694f8e6991` |
+| ruby | `tree-sitter-ruby.wasm` | `93a5022855314cdb45458c7bb026a24a0ebc3a5ff6439e542e881f14dfa13a39` |
 
-All seven are built against **grammar ABI 14** (`EXPECTED_GRAMMAR_ABI` in
+All eight are built against **grammar ABI 14** (`EXPECTED_GRAMMAR_ABI` in
 `src/scripts/code_graph/types.ts`). The loader asserts the ABI on every load, so
 a drifted grammar fails loudly rather than parsing wrongly.
 
@@ -39,7 +40,7 @@ a drifted grammar fails loudly rather than parsing wrongly.
 
 Copied byte-for-byte from `tree-sitter-wasms@0.1.13`
 (<https://github.com/Gregoor/tree-sitter-wasms>, Unlicense), which compiles them
-from the upstream `tree-sitter/tree-sitter-{php,typescript,javascript}` grammars
+from the upstream `tree-sitter/tree-sitter-{php,typescript,javascript,python,go,java,c-sharp,ruby}` grammars
 (MIT). The compiled artifacts are derivatives of the MIT grammar sources, so
 they are annotated MIT in `REUSE.toml` and credited in `CREDITS.md`.
 
@@ -74,7 +75,7 @@ The pair is ABI-coupled and must move together:
 
 ```bash
 npm i -D web-tree-sitter@<v> tree-sitter-wasms@<v>
-for g in php typescript javascript python go java c_sharp; do
+for g in php typescript javascript python go java c_sharp ruby; do
   cp node_modules/tree-sitter-wasms/out/tree-sitter-$g.wasm src/vendor/grammars/
 done
 shasum -a 256 src/vendor/grammars/*.wasm   # update the table above
@@ -82,7 +83,7 @@ shasum -a 256 src/vendor/grammars/*.wasm   # update the table above
 
 Then update, in the same change:
 
-- the seven entries in `src/config/packed-binary-manifest.json` (they are
+- the eight entries in `src/config/packed-binary-manifest.json` (they are
   path-, sha256- and size-bound, so any refresh invalidates them by design).
   This used to name `BINARY_PAYLOAD_EXCEPTIONS` in `src/scripts/check_pack_size.ts`,
   a constant that no longer exists — `grep -rn BINARY_PAYLOAD_EXCEPTIONS` returned