chainlesschain 0.166.140 → 0.166.142

package/src/lib/plugin-runtime/cli-project-goal-events.js

@@ -0,0 +1,212 @@
+/** A separately consented v4 lease observes bounded native evidence snapshots. */
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { setTimeout as delay } from "node:timers/promises";
+import { createHash } from "node:crypto";
+import { cliGoalExtensionHost } from "./cli-goal-capabilities.js";
+import { managedSettingsPath } from "../settings-loader.cjs";
+import { createProjectGoalConnection } from "../project-goal-connection.js";
+import {
+  collectGoalExtensions,
+  projectGoalExtensionEvent,
+} from "./goal-extensions.js";
+
+const TYPES = ["risk.review.completed", "action.receipt.updated"];
+const SCHEMA = "chainlesschain.goal-extension-stream/v1";
+export const _deps = { createProjectGoalConnection, projectGoalExtensionEvent };
+const fail = (code) => {
+  throw new Error(code);
+};
+const digest = (value) =>
+  createHash("sha256").update(JSON.stringify(value)).digest("hex");
+
+/** Capture options before any I/O. Never reinterpret another lease as events. */
+export function watchCliProjectGoalEvents(id, options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const env = Object.freeze({ ...(options.env || process.env) });
+  const managedSettingsFile = managedSettingsPath({
+    env,
+    managedSettingsFile: options.managedSettingsFile,
+  });
+  const name = options.plugin,
+    scope = options.scope,
+    expectedStore = options.expectedStore;
+  const connectionFile = options.connection;
+  const intervalMs = options.intervalMs ?? 1000,
+    durationMs = options.durationMs ?? 60000;
+  const signal = options.signal;
+  if (typeof name !== "string" || !name || name.length > 256)
+    fail("CLI_GOAL_INVALID_PLUGIN_NAME");
+  if (scope !== undefined && !["user", "project", "local"].includes(scope))
+    fail("CLI_GOAL_INVALID_PLUGIN_SCOPE");
+  if (
+    !Number.isSafeInteger(intervalMs) ||
+    intervalMs < 250 ||
+    intervalMs > 60000 ||
+    !Number.isSafeInteger(durationMs) ||
+    durationMs < 1000 ||
+    durationMs > 900000
+  )
+    fail("CLI_GOAL_INVALID_WATCH_LIMIT");
+  if (signal !== undefined && !(signal instanceof AbortSignal))
+    fail("CLI_GOAL_INVALID_WATCH_SIGNAL");
+  const host = cliGoalExtensionHost(TYPES.map((type) => `event:${type}`));
+  const admission = Object.freeze({ cwd, env, managedSettingsFile, host });
+  return (async function* () {
+    if (signal?.aborted) return;
+    const source = _deps.createProjectGoalConnection(connectionFile);
+    if (!source.events || typeof source.readEvents !== "function")
+      fail("CLI_GOAL_EVENT_CONNECTION_REQUIRED");
+    const goalRef = source.goalRef;
+    if (
+      id !== goalRef.id ||
+      (expectedStore !== undefined && expectedStore !== goalRef.storeId)
+    )
+      fail("CLI_GOAL_STORE_MISMATCH");
+    const matches = collectGoalExtensions(admission).extensions.filter(
+      (entry) =>
+        entry.name === name &&
+        (!scope || entry.scope === scope) &&
+        entry.declaration.events.some((type) => TYPES.includes(type)),
+    );
+    if (matches.length !== 1) fail("CLI_GOAL_EVENT_PLUGIN_UNAVAILABLE");
+    const plugin = matches[0];
+    const ref = Object.freeze({
+      name: plugin.name,
+      scope: plugin.scope,
+      version: plugin.version,
+    });
+    const declaration = digest(plugin.declaration);
+    function revalidatePlugin() {
+      const current = collectGoalExtensions(admission).extensions.find(
+        (entry) =>
+          entry.name === ref.name &&
+          entry.scope === ref.scope &&
+          entry.version === ref.version,
+      );
+      if (!current || digest(current.declaration) !== declaration)
+        fail("CLI_GOAL_EVENT_ADMISSION_CHANGED");
+    }
+    const deadline = performance.now() + durationMs;
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    const timer = setTimeout(stop, durationMs);
+    timer.unref();
+    signal?.addEventListener("abort", stop, { once: true });
+    if (signal?.aborted) stop();
+    async function read() {
+      revalidatePlugin();
+      const value = await source.readEvents(id, { signal: controller.signal });
+      revalidatePlugin();
+      return value;
+    }
+    async function revalidate(snapshot) {
+      if (digest(await read()) !== digest(snapshot))
+        fail("CLI_GOAL_EVENT_SOURCE_CHANGED");
+    }
+    try {
+      let previous = await read();
+      await revalidate(previous);
+      if (controller.signal.aborted) return;
+      yield Object.freeze({
+        schema: SCHEMA,
+        kind: "ready",
+        source: "desktop-project",
+        plugin: ref,
+        goalRef,
+        observedAt: new Date().toISOString(),
+        delivery: "polling",
+        replay: false,
+      });
+      while (!controller.signal.aborted && performance.now() < deadline) {
+        await delay(
+          Math.min(intervalMs, Math.max(1, deadline - performance.now())),
+          undefined,
+          { signal: controller.signal },
+        );
+        if (controller.signal.aborted || performance.now() >= deadline) return;
+        const current = await read();
+        if (digest(current) === digest(previous)) continue;
+        const events = [];
+        if (
+          (previous.risk.reviewId && !current.risk.reviewId) ||
+          (previous.receipts.state === "recorded" &&
+            current.receipts.state !== "recorded")
+        )
+          fail("CLI_GOAL_EVENT_SOURCE_REGRESSED");
+        if (
+          current.risk.reviewId &&
+          digest(current.risk) !== digest(previous.risk) &&
+          plugin.declaration.events.includes(TYPES[0])
+        )
+          events.push({
+            type: TYPES[0],
+            summary: `Historical risk check ${current.risk.reviewId}: ${current.risk.state}; risk task count ${current.risk.riskTaskCount ?? "unknown"}. Current risk and goal completion require native verification.`,
+          });
+        for (const receipt of current.receipts.entries) {
+          const before = previous.receipts.entries.find(
+            (entry) => entry.id === receipt.id,
+          );
+          if (
+            before &&
+            before.status !== "unresolved" &&
+            digest(before) !== digest(receipt)
+          )
+            fail("CLI_GOAL_EVENT_SOURCE_REGRESSED");
+          if (
+            (!before || digest(receipt) !== digest(before)) &&
+            plugin.declaration.events.includes(TYPES[1])
+          )
+            events.push({
+              type: TYPES[1],
+              summary: `Historical action receipt ${receipt.id}: ${receipt.status} (${receipt.actionType}). This does not prove goal completion.`,
+            });
+        }
+        for (const candidate of events) {
+          const observedAt = new Date().toISOString();
+          const event = await _deps.projectGoalExtensionEvent(
+            ref,
+            { type: candidate.type, goalRef },
+            {
+              ...admission,
+              async authorize(context) {
+                if (
+                  context.operation !== "read-event" ||
+                  context.type !== candidate.type ||
+                  JSON.stringify(context.goalRef) !== JSON.stringify(goalRef)
+                )
+                  return false;
+                await revalidate(current);
+                return true;
+              },
+              async readEvent() {
+                await revalidate(current);
+                return { summary: candidate.summary, occurredAt: observedAt };
+              },
+            },
+          );
+          await revalidate(current);
+          if (controller.signal.aborted || performance.now() >= deadline)
+            return;
+          yield Object.freeze({
+            schema: SCHEMA,
+            kind: "event",
+            source: "desktop-project",
+            plugin: ref,
+            observedAt,
+            delivery: "polling",
+            replay: false,
+            event,
+          });
+        }
+        previous = current;
+      }
+    } catch (error) {
+      if (!controller.signal.aborted) throw error;
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", stop);
+      controller.abort();
+    }
+  })();
+}

package/src/lib/plugin-runtime/examples/goal-project-observer/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "goal-project-observer",
+  "version": "0.1.0",
+  "description": "Observe bounded native risk-check and action-receipt summaries through a separately authorized desktop event connection",
+  "permissions": {
+    "goalExtension": [
+      "event:risk.review.completed",
+      "event:action.receipt.updated"
+    ]
+  },
+  "goalExtension": {
+    "apiVersion": "1.0.0",
+    "hosts": {
+      "cli": ">=0.166.142"
+    },
+    "events": ["risk.review.completed", "action.receipt.updated"],
+    "panels": [],
+    "proposals": []
+  }
+}

package/src/lib/plugin-runtime/examples/goal-status-observer/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "goal-status-observer",
+  "version": "0.1.0",
+  "description": "Observe status changes of one explicitly selected standalone CLI goal",
+  "permissions": {
+    "goalExtension": ["event:goal.status.changed"]
+  },
+  "goalExtension": {
+    "apiVersion": "1.0.0",
+    "hosts": {
+      "cli": ">=0.166.142"
+    },
+    "events": ["goal.status.changed"],
+    "panels": [],
+    "proposals": []
+  }
+}

package/src/lib/plugin-runtime/examples/project-delivery-assistant/README.md

@@ -0,0 +1,92 @@
+# Project delivery assistant 0.2.0
+
+This data-only scenario package combines evidence panels, bounded observations,
+retained event replay and user-selected task-description drafts. It runs through
+the existing CLI and both IDE plugin managers. Requires CLI 0.166.142, Session
+Core 0.3.25 and a matching desktop build with the separately authorized goal
+connections. Paired IDE releases are Open VSX 0.37.178 and JetBrains 0.4.195.
+The version ranges in the manifest are compatibility floors; each operation
+still needs its native source authorization.
+
+The package contains no hooks, binaries, arbitrary code or autonomous scheduler.
+It does not create tasks, choose a description for you, approve actions or mark a
+goal complete. Task creation remains a future extension surface.
+
+From the repository root, install at the scope you will use:
+
+```powershell
+cc plugin add packages/cli/src/lib/plugin-runtime/examples/project-delivery-assistant --scope project --json
+cc plugin trust project-delivery-assistant --scope project
+cc plugin consent project-delivery-assistant --scope project --grant --json
+```
+
+Consent covers the full declared capability set. Each command still needs its
+own selected source and separate desktop authorization:
+
+| Entry                                                               | Source and result                                                                                                                                           |
+| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `goal panels`                                                       | A separately authorized evidence connection; objective/status and historical risk/receipt summary. A summary-only connection cannot supply evidence fields. |
+| `goal watch` with a connection                                      | A v4 event connection; risk-check and action-receipt observations for a bounded interval. Polling can miss intermediate changes.                            |
+| `goal watch` without a connection                                   | A standalone CLI goal; status changes only. This does not subscribe to native project status.                                                               |
+| `goal replay`                                                       | A v5 retained-history connection and explicit new/resume checkpoint; one page per invocation.                                                               |
+| `goal draft-access`, `draft-sources`, `draft-send`, `draft-receipt` | A separate v3 pending-draft authorization bound to this plugin/version/declaration. The user selects a current native source and a UTF-8 description file.  |
+
+In the desktop goal area, export the relevant connection with its separate native
+confirmation. Connections are short-lived and tied to the active identity and
+goal revision; keep their private files local. One connection does not grant the
+other surfaces. For example:
+
+```powershell
+cc goal panels <goal-id> --connection "<evidence.json>" --plugin project-delivery-assistant --scope project --json
+cc goal watch <goal-id> --connection "<events-v4.json>" --plugin project-delivery-assistant --scope project --duration 60 --json
+cc goal replay <goal-id> --connection "<history-v5.json>" --checkpoint "<checkpoint.json>" --checkpoint-mode new --plugin project-delivery-assistant --scope project --json
+# Subsequent explicit page: use the same checkpoint and --checkpoint-mode resume.
+cc goal replay <goal-id> --connection "<history-v5.json>" --checkpoint "<checkpoint.json>" --checkpoint-mode resume --plugin project-delivery-assistant --scope project --json
+```
+
+Replay scans at most 20 retained events per page. Exit zero confirms checkpoint
+commit; output alone does not. Keep the checkpoint after interruption because it
+may already have advanced. Delivery can repeat event IDs. The newest 1000
+instrumented events are retained; pre-instrumentation history is not backfilled.
+Retention gaps and database regression are reported, without automatic reset.
+
+For a pending description draft, export this plugin's access request first:
+
+```powershell
+cc goal draft-access --plugin project-delivery-assistant --scope project --out "<new-access.json>" --json
+```
+
+In the desktop, choose the separate online-draft authorization and select that
+access file. In either IDE select **Send online draft…** / **Submit pending
+draft…**, pick the v3 connection, a current native source, the proposed description
+and a new submission-record file. Alternatively use the CLI:
+
+```powershell
+cc goal draft-sources <goal-id> --connection "<draft-v3.json>" --plugin project-delivery-assistant --scope project --json
+cc goal draft-send <goal-id> --connection "<draft-v3.json>" --plugin project-delivery-assistant --scope project --source "<source-id>" --request-id "<stable-request-id>" --title "Delivery follow-up" --description-file "<description.txt>" --record "<new-submission.json>" --json
+cc goal draft-receipt <goal-id> --connection "<draft-v3.json>" --plugin project-delivery-assistant --scope project --record "<submission.json>" --json
+```
+
+A saved draft is pending. Open it in the desktop, inspect the current native
+preview, then confirm through the existing action flow. Read the real receipt
+and run a fresh risk check to assess the outcome; a description edit does not
+prove that a deadline or dependency risk was resolved. If submission is unknown,
+keep its record and look up the receipt before deciding whether to send again.
+
+In VS Code / JetBrains choose this installed plugin, then **CLI goal panels…**,
+**Observe desktop events…**, **Recover retained history…** or the draft controls.
+Recovery uses native connection and new/resume checkpoint dialogs; **Read next
+page / check again** is explicit. No automatic observation, retry or business
+action starts when the package is installed or reinstalled.
+
+Disable or uninstall using the normal plugin controls. New operations are refused,
+and active observers stop when they recheck admission. Native goals, actions,
+receipts and saved checkpoints stay in their existing stores. Reinstalling keeps
+the existing trust/consent policy, and requires a new explicit command or IDE
+action to read again; it does not reconnect by itself. Version changes require
+project trust again, capability expansion requires new consent, and a changed
+declaration/goal binding requires a matching new desktop authorization and an
+explicit new checkpoint when the old binding no longer matches.
+
+Real IDE/Electron GUI journeys, automatic drafting, task-creation proposals,
+independent business-effect evaluation and release gates remain pending.

package/src/lib/plugin-runtime/examples/project-delivery-assistant/plugin.json

@@ -1,23 +1,22 @@
 {
   "name": "project-delivery-assistant",
-  "version": "0.1.0",
-  "description": "Declarative project delivery assistant prototype; requires a goal extension host adapter",
+  "version": "0.2.0",
+  "description": "Project evidence, bounded event observation and retained replay, and user-selected description drafts through separately authorized CLI surfaces",
   "permissions": {
     "goalExtension": [
       "event:goal.status.changed",
       "event:risk.review.completed",
       "event:action.receipt.updated",
       "panel:goal.evidence",
-      "proposal:task.create",
       "proposal:task.description.update"
     ]
   },
   "goalExtension": {
     "apiVersion": "1.0.0",
     "hosts": {
-      "cli": ">=0.166.104",
-      "vscode": ">=0.37.149",
-      "jetbrains": ">=0.4.166"
+      "cli": ">=0.166.142",
+      "vscode": ">=0.37.178",
+      "jetbrains": ">=0.4.195"
     },
     "events": [
       "goal.status.changed",
@@ -33,6 +32,6 @@
         "fallback": "text"
       }
     ],
-    "proposals": ["task.create", "task.description.update"]
+    "proposals": ["task.description.update"]
   }
 }

package/src/lib/plugin-runtime/goal-extensions.js

@@ -36,6 +36,11 @@ function fixedHostOptions(options) {
       id: options.host?.id,
       version: options.host?.version,
       capabilities: Object.freeze([...(options.host?.capabilities || [])]),
+      activeCapabilities: Object.freeze([
+        ...(options.host?.activeCapabilities ??
+          options.host?.capabilities ??
+          []),
+      ]),
     }),
     authorize: options.authorize,
     readEvent: options.readEvent,
@@ -44,6 +49,14 @@ function fixedHostOptions(options) {
   });
 }
 
+function requireActiveCapability(options, capability) {
+  if (
+    !options.host.capabilities.includes(capability) ||
+    !options.host.activeCapabilities.includes(capability)
+  )
+    throw new Error("goal extension capability is inactive for this operation");
+}
+
 /** Compatibility and mandatory consent are independent of legacy policy flags. */
 export function collectGoalExtensions(options = {}) {
   const extensions = [];
@@ -139,6 +152,7 @@ export async function projectGoalExtensionEvent(ref, request, options = {}) {
   options = fixedHostOptions(options);
   const type = request?.type;
   const plugin = admittedPlugin(ref, options, "events", type);
+  requireActiveCapability(options, `event:${type}`);
   const source = goalRef(request.goalRef);
   const context = Object.freeze({
     plugin: Object.freeze({
@@ -182,6 +196,7 @@ export async function projectGoalExtensionPanel(ref, request, options = {}) {
     (entry) => entry.id === request?.panelId,
   );
   if (!panel) throw new Error("goal extension panel is undeclared");
+  requireActiveCapability(options, `panel:${panel.slot}`);
   const source = goalRef(request.goalRef);
   const context = Object.freeze({
     plugin: Object.freeze({
@@ -229,6 +244,7 @@ export async function proposeGoalExtensionAction(ref, raw, options = {}) {
   raw = normalizeGoalExtensionProposal(raw);
   if (!plugin.declaration.proposals.includes(raw.type))
     throw new Error("goal extension proposal is undeclared");
+  requireActiveCapability(options, `proposal:${raw.type}`);
   const source = raw.goalRef;
   const title = raw.title;
   const description = raw.description;

package/src/lib/project-goal-connection.js

@@ -5,7 +5,11 @@ import http from "node:http";
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { inspectPrivatePath } from "@chainlesschain/session-core/private-storage";
 import { goalExtensionRef } from "@chainlesschain/session-core/goal-extension-proposal-contract";
-import { validateGoalEvidenceProjection } from "@chainlesschain/session-core/goal-evidence-contract";
+import {
+  validateGoalEvidenceProjection,
+  validateGoalEventHistoryPage,
+  parseGoalEventCursor,
+} from "@chainlesschain/session-core/goal-evidence-contract";
 import { validateGoalDraftDescriptor } from "@chainlesschain/session-core/goal-draft-connection-contract";
 import { createProjectGoalDraftClient } from "./project-goal-draft-connection.js";
 function fail() {
@@ -59,17 +63,32 @@ export function createProjectGoalConnection(file) {
     }
     const evidence =
       descriptor.schema === "chainlesschain.project-goal-connection/v2";
-    const endpointPath = evidence ? "/goal-evidence" : "/goal-summary";
+    const events =
+      descriptor.schema === "chainlesschain.project-goal-connection/v4";
+    const history =
+      descriptor.schema === "chainlesschain.project-goal-connection/v5";
+    const endpointPath = history
+      ? "/goal-event-history"
+      : events
+        ? "/goal-events"
+        : evidence
+          ? "/goal-evidence"
+          : "/goal-summary";
     if (
       Object.keys(descriptor).sort().join() !==
-        (evidence
+        (evidence || events || history
           ? "capability,endpoint,expiresAt,goalRef,key,schema"
           : "endpoint,expiresAt,goalRef,key,schema") ||
-      (evidence
-        ? descriptor.capability !== "goal.evidence"
-        : descriptor.schema !== "chainlesschain.project-goal-connection/v1") ||
+      (history
+        ? descriptor.capability !== "goal.event-history"
+        : events
+          ? descriptor.capability !== "goal.events"
+          : evidence
+            ? descriptor.capability !== "goal.evidence"
+            : descriptor.schema !==
+              "chainlesschain.project-goal-connection/v1") ||
       typeof descriptor.endpoint !== "string" ||
-      !/^http:\/\/127\.0\.0\.1:[1-9][0-9]{0,4}\/goal-(?:summary|evidence)$/.test(
+      !/^http:\/\/127\.0\.0\.1:[1-9][0-9]{0,4}\/goal-(?:summary|evidence|events|event-history)$/.test(
         descriptor.endpoint,
       ) ||
       new URL(descriptor.endpoint).pathname !== endpointPath ||
@@ -93,22 +112,26 @@ export function createProjectGoalConnection(file) {
       createHmac("sha256", Buffer.from(descriptor.key, "hex"))
         .update(value)
         .digest("hex");
-    async function read(id = ref.id) {
+    async function read(id = ref.id, { signal, after } = {}) {
       validate();
       if (id !== ref.id) fail();
+      if (after !== undefined && !history) fail();
+      if (after !== undefined) parseGoalEventCursor(after);
+      const requestPath =
+        endpointPath + (after === undefined ? "" : `?after=${after}`);
       const nonce = randomBytes(32).toString("hex");
       try {
         const result = await new Promise((resolve, reject) => {
           const request = http.get(
-            descriptor.endpoint,
+            descriptor.endpoint +
+              (after === undefined ? "" : `?after=${after}`),
             {
               agent: false,
+              signal,
               maxHeaderSize: 4096,
               headers: {
                 "X-CC-Nonce": nonce,
-                "X-CC-Signature": mac(
-                  `request\nGET\n${endpointPath}\n${nonce}`,
-                ),
+                "X-CC-Signature": mac(`request\nGET\n${requestPath}\n${nonce}`),
               },
             },
             (response) => {
@@ -124,19 +147,48 @@ export function createProjectGoalConnection(file) {
                 const body = Buffer.concat(chunks).toString("utf8"),
                   signature = response.headers["x-cc-signature"];
                 if (
-                  response.statusCode !== 200 ||
+                  (!history && response.statusCode !== 200) ||
                   typeof signature !== "string" ||
                   !/^[a-f0-9]{64}$/.test(signature) ||
                   !timingSafeEqual(
                     Buffer.from(signature),
-                    Buffer.from(mac(`response\n${nonce}\n${body}`)),
+                    Buffer.from(
+                      mac(
+                        history
+                          ? `response\n${nonce}\n${response.statusCode}\n${body}`
+                          : `response\n${nonce}\n${body}`,
+                      ),
+                    ),
                   )
                 ) {
                   reject(new Error("signature"));
                   return;
                 }
                 try {
-                  resolve(JSON.parse(body));
+                  const parsed = JSON.parse(body);
+                  if (history && response.statusCode !== 200) {
+                    if (
+                      [409, 410].includes(response.statusCode) &&
+                      Object.keys(parsed).join() === "error" &&
+                      [
+                        "GOAL_EVENT_CURSOR_INVALID",
+                        "GOAL_EVENT_HISTORY_GAP",
+                        "GOAL_EVENT_HISTORY_REGRESSED",
+                        "GOAL_EVENT_HISTORY_UNAVAILABLE",
+                        "GOAL_EVENT_HISTORY_INVALID",
+                      ].includes(parsed.error)
+                    ) {
+                      reject(
+                        Object.assign(new Error(parsed.error), {
+                          code: parsed.error,
+                        }),
+                      );
+                      return;
+                    }
+                    reject(new Error("status"));
+                    return;
+                  }
+                  resolve(parsed);
                 } catch {
                   reject(new Error("json"));
                 }
@@ -152,34 +204,66 @@ export function createProjectGoalConnection(file) {
           request.on("error", reject);
         });
         validate();
+        if (history) return validateGoalEventHistoryPage(result, ref, after);
         if (
           Object.keys(result).sort().join() !==
-            (evidence
-              ? "goalRef,objective,receipts,risk,schema,status"
-              : "goalRef,objective,schema,status") ||
+            (events
+              ? "goalRef,receipts,risk,schema"
+              : evidence
+                ? "goalRef,objective,receipts,risk,schema,status"
+                : "goalRef,objective,schema,status") ||
           result.schema !==
-            (evidence
-              ? "chainlesschain.project-goal-evidence/v1"
-              : "chainlesschain.project-goal-summary/v1") ||
+            (events
+              ? "chainlesschain.project-goal-events/v1"
+              : evidence
+                ? "chainlesschain.project-goal-evidence/v1"
+                : "chainlesschain.project-goal-summary/v1") ||
           JSON.stringify(goalExtensionRef(result.goalRef)) !==
             JSON.stringify(ref) ||
-          typeof result.objective !== "string" ||
-          result.objective.length > 4096 ||
-          result.status !== "active"
+          (!events &&
+            (typeof result.objective !== "string" ||
+              result.objective.length > 4096 ||
+              result.status !== "active"))
         )
           fail();
-        if (evidence)
+        if (evidence || events)
           validateGoalEvidenceProjection({
             risk: result.risk,
             receipts: result.receipts,
           });
         return { ...result, goalRef: ref };
-      } catch {
+      } catch (error) {
+        if (
+          history &&
+          [
+            "GOAL_EVENT_CURSOR_INVALID",
+            "GOAL_EVENT_HISTORY_GAP",
+            "GOAL_EVENT_HISTORY_REGRESSED",
+            "GOAL_EVENT_HISTORY_UNAVAILABLE",
+            "GOAL_EVENT_HISTORY_INVALID",
+          ].includes(error.code)
+        )
+          throw error;
         fail();
       }
     }
     validate();
-    return Object.freeze({ goalRef: ref, evidence, read });
+    return history
+      ? Object.freeze({
+          goalRef: ref,
+          eventHistory: true,
+          readEventPage: (after, options = {}) =>
+            read(ref.id, { ...options, after }),
+          read: async () => fail(),
+        })
+      : events
+        ? Object.freeze({
+            goalRef: ref,
+            events: true,
+            readEvents: read,
+            read: async () => fail(),
+          })
+        : Object.freeze({ goalRef: ref, evidence, read });
   } catch {
     fail();
   } finally {