fullstackgtm 0.26.0 → 0.28.0

package/CHANGELOG.md

@@ -5,6 +5,89 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/).
 The path to 1.0 is planned in [docs/roadmap-to-1.0.md](./docs/roadmap-to-1.0.md).
 
+## [0.28.0] — 2026-06-16
+
+Connectors, credentials & supply chain — the last of the hardening train.
+Each security change was re-attacked; the keychain and supply-chain gates each
+took two rounds (the re-attack found the stale-plaintext-on-migration gap and
+the orphan-dist gap that round 1 left open).
+
+### Added
+
+- **Opt-in OS-keychain credential storage** (`FSGTM_KEYCHAIN=1`). The credential
+  blob is stored in the macOS Keychain (`security`) or Linux libsecret
+  (`secret-tool`) instead of a 0600 file — no native dependency. Enabling it on
+  an existing install migrates `credentials.json` into the keychain and removes
+  the plaintext file. Default (unset) is unchanged: the 0600 file. macOS caveat
+  (transient argv exposure during the keychain write) documented in SECURITY.md.
+
+### Security
+
+- **Broker URL must be https.** `login --via` and the token-mint path refuse a
+  cleartext/non-https broker (localhost dev excepted), and the device
+  verification URL is only auto-opened when it shares the `--via` origin — so a
+  long-lived pairing bearer and minted live-CRM tokens can't go over cleartext
+  or to an attacker-redirected URL.
+- **Supply-chain: published dist is provably from source.** `npm run build` now
+  cleans first; release rebuilds from source and refuses to publish if the
+  committed `dist/` doesn't match (catching a poisoned or *orphaned* dist file),
+  and a CI `dist-integrity` job enforces the same on every push — protecting
+  `npm install github:` consumers who run the committed dist unbuilt.
+- npx peer resolution from the current directory is now logged (running the MCP
+  server in an untrusted directory could otherwise silently load a peer from it).
+
+### Changed
+
+- **Salesforce merge is documented as unsupported**, with a connector
+  capability matrix in the README — no REST merge exists (SOAP/Apex only), so
+  `merge_records` is refused honestly; deduplicate in the UI or archive the
+  non-survivors. No silent half-merge, no demo surprise.
+
+## [0.27.0] — 2026-06-16
+
+Trust, compliance & transparency — the artifacts a skeptical buyer's security
+and procurement review asks for, plus an exportable audit trail and two
+content-grounding fixes. Security-relevant additions were re-attacked before
+release (the audit-log signing and the transcript gate each took two rounds).
+
+### Added
+
+- **`audit-log export` / `audit-log verify`** — a tamper-evident record of every
+  apply run, flattened across all plans into a hash chain, with the head
+  HMAC-signed by the per-install key. Exports are always signed; `verify`
+  recomputes the chain and refuses an edited, reordered, truncated, or
+  signature-stripped log (and reports it as unverifiable on a machine without
+  the key). The change-management/SIEM artifact the prior audit flagged as
+  missing.
+- **`SECURITY.md`** — disclosure address (security@fullstackgtm.com) and the
+  full trust model (credential custody, approval gating, approval-integrity
+  signing, scheduling, untrusted-input handling, auditability).
+- **`DATA-FLOWS.md`** — exactly what data leaves the machine, to which endpoint,
+  for which command, and under whose account; the "CLI is BYO-key, no
+  vendor data path, no sub-processors" statement procurement needs; and how to
+  run the whole loop with zero third-party calls.
+- **Company-of-record** — `package.json` author and a `NOTICE` file now name
+  Full Stack GTM with a contact; LICENSE unchanged (Apache-2.0).
+
+### Security
+
+- **Call-transcript insight grounding.** LLM-extracted call insights are now
+  mechanically verified: the evidence quote must be a non-trivial verbatim span
+  of the transcript, and for `next_step` (the only insight whose text is written
+  to the CRM) the written action itself must be grounded in that quote — every
+  number/amount must appear in the quote, and the action's distinctive terms
+  must overlap it. This closes the prompt-injection path where a transcript
+  fabricates a malicious next step accompanied by an innocuous real quote. (This
+  is defense-in-depth on a human-approved path; a determined paraphrase-style
+  injection still surfaces to the approver as the proposed value.)
+
+### Changed
+
+- README now states the design as **deterministic apply, governed suggest** and
+  cites the current 1,020-run / five-model benchmark (was a stale 612-run line);
+  a CI guard fails if the documented synthetic-scenario count drifts from the
+  code.
+
 ## [0.26.0] — 2026-06-15
 
 Write-path integrity — the "no write without approval" guarantee now binds to

package/DATA-FLOWS.md

@@ -0,0 +1,52 @@
+# Data flows & trust boundary
+
+A procurement / security review needs to know exactly what data leaves the
+machine, to which endpoint, and under whose account. This is that enumeration
+for the open-source `fullstackgtm` CLI. The short version: **the CLI is
+bring-your-own-key and talks directly to services you already control — there
+is no fullstackgtm-operated server in the data path for the open package.**
+
+## What stays local
+
+- CRM snapshots, patch plans, approvals, apply-run records, market captures and
+  observations, enrich run state, and the signing/credential stores all live
+  under `$FSGTM_HOME` (default `~/.fullstackgtm`), `0600`/`0700`. Nothing is
+  uploaded to Full Stack GTM.
+- No telemetry, analytics, or phone-home. The core package has zero runtime
+  dependencies; the only network calls are the ones listed below, all to
+  endpoints you configure.
+
+## What leaves the machine, by command
+
+| Command(s) | Destination | Data sent | Auth |
+|---|---|---|---|
+| `snapshot`, `audit`, `apply`, `resolve`, `bulk-update`, `dedupe`, `reassign`, `fix`, `enrich` (writeback) | **Your CRM** (HubSpot / Salesforce / Stripe API) | Reads: your CRM records. Writes: only approved patch operations. | Your CRM token (env / stored / broker) |
+| `call parse`, `call score`, `market classify`, `market refresh` | **Your LLM provider** (api.anthropic.com or api.openai.com) | The call transcript / captured competitor page text you point at, plus the extraction prompt | Your `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` (BYO) |
+| `enrich append --source apollo`, `enrich refresh` | **Apollo** (api.apollo.io) | The company domain / contact email being enriched | Your `APOLLO_API_KEY` (BYO) |
+| `market capture`, `market refresh` | **Public vendor websites** you list in `market.config.json` | An HTTP GET (no data sent beyond the request); SSRF-guarded to public hosts only | none |
+| `login --via <url>` (optional) | **Your hosted deployment's broker** | A pairing handshake; the broker mints short-lived CRM tokens | broker pairing token |
+
+Commands not listed (`plans`, `rules`, `doctor`, `schedule`, `audit-log`,
+`diff`, `merge`, report rendering) make **no network calls**.
+
+## Avoiding third-party data egress
+
+- **LLM verbs are optional.** `call parse --deterministic` uses a free,
+  offline keyword baseline (no LLM call). `market worksheet` lets an agent or
+  human classify without the CLI making an LLM call. A regulated deployment can
+  run the full audit → plan → apply loop with **zero third-party calls** —
+  CRM-only.
+- **No data is sent for training.** Anthropic, OpenAI, and Apollo are reached
+  with your own API keys under your own agreements; their data-handling terms
+  (and any DPA you have with them) govern that traffic. Full Stack GTM is not
+  in that path and is not a sub-processor for the open-source CLI.
+
+## Sub-processors
+
+For the **open-source CLI**: none (BYO-key, direct-to-service). The data
+controllers are you and the providers whose keys you supply.
+
+For the **hosted application** (a separate, proprietary product — not this
+package): a sub-processor list and DPA are provided through that product's
+agreement. If you are evaluating the hosted product, request them from
+security@fullstackgtm.com.

package/NOTICE

@@ -0,0 +1,5 @@
+fullstackgtm
+Copyright 2026 Full Stack GTM
+
+This product is developed and maintained by Full Stack GTM (https://fullstackgtm.com).
+Licensed under the Apache License, Version 2.0 (see LICENSE).

package/README.md

@@ -127,7 +127,7 @@ fullstackgtm reassign --from 411 --to 902 --except-deal-stage closing --save   #
 fullstackgtm fix --rule missing-deal-owner --provider hubspot --yes  # audit one rule → suggest → approve → apply, one command
 ```
 
-`bulk-update` filters the snapshot (`=`, `!=`, `~` substring, `!~` not-substring, `:empty`/`:notempty`, `|` any-of, relational pseudo-fields like `account.domain` or `openDealStages`) into a dry-run patch plan — and **the full filter is re-verified per record at apply time**, with mid-apply rechecks, so a record that stopped matching between audit and apply is skipped, not clobbered. Equality filters double as preconditions; `--require` adds explicit ones; `--guard` asserts cross-record conditions; `--max-operations` caps blast radius. `--set field=from:<sourceField>` derives values per record; `--create-task <text>` is the third change mode, emitting approval-gated `create_task` operations instead of field writes; `--archive` refuses records whose identity key (account domain, contact email) is shared with another record — that's a duplicate, and duplicates are merged with `dedupe`, not archived around (`--force-archive-duplicates` overrides that refusal explicitly).
+`bulk-update` filters the snapshot (`=`, `!=`, `~` substring, `!~` not-substring, `:empty`/`:notempty`, type-aware comparisons `<` `>` `<=` `>=` where `today` resolves to the policy date — e.g. `closeDate<today` — and date/numeric fields coerce by value form, `|` any-of, relational pseudo-fields like `account.domain` or `openDealStages`) into a dry-run patch plan — and **the full filter is re-verified per record at apply time**, with mid-apply rechecks, so a record that stopped matching between audit and apply is skipped, not clobbered. For date/count hygiene (past close dates, stale deals, missing accounts, duplicates), prefer the rule-backed `fix --rule <id>` — the rule encodes the open-deal + date logic deterministically; use `bulk-update` only when no rule covers the task. Equality filters double as preconditions; `--require` adds explicit ones; `--guard` asserts cross-record conditions; `--max-operations` caps blast radius. `--set field=from:<sourceField>` derives values per record; `--create-task <text>` is the third change mode, emitting approval-gated `create_task` operations instead of field writes; `--archive` refuses records whose identity key (account domain, contact email) is shared with another record — that's a duplicate, and duplicates are merged with `dedupe`, not archived around (`--force-archive-duplicates` overrides that refusal explicitly).
 
 `dedupe` finds duplicate groups by normalized identity key and emits one `merge_records` operation per group with a deterministic survivor (`richest` = most populated fields, ties to lowest id; `oldest`). Merges stay irreversible-and-therefore-low-confidence-capped on approval, exactly like merge suggestions from the audit. `reassign` is the ownership-handoff playbook: one plan per object type, extra scoping account-lifted to deals and contacts, and `--except-deal-stage` excludes both deals in that stage and every record whose account has an open deal in it. `fix` is the one-shot composite for a single rule: audit → save → suggest → approve suggestion-backed operations at the confidence bar → with `--yes`, apply and print the stage-by-stage summary; without it, stop after approval and print the apply command.
 
@@ -219,7 +219,9 @@ fullstackgtm diff --before old.json --after new.json --fail-on-new-findings
 - `--demo` (with `--seed`) generates a realistic mid-market CRM with injected real-world failure modes — departed owners, unlinked deals, orphan accounts, stale pipeline — so agents and CI can exercise the full snapshot → audit → apply pipeline with zero credentials.
 - Exit codes: `0` success, `1` error, `2` findings at/above `--fail-on`.
 
-"Built for agents" is measured, not asserted: a 612-run benchmark (17 scenarios × 3 tool-surface arms × 4 trials, deterministic graders over final CRM state, τ-bench-style pass^k) shows the gated CLI surface beating raw CRM-API access on completion-under-policy for every model tested. Full matrix and methodology: [the leaderboard](./evals/crm/leaderboard/RESULTS.md).
+"Built for agents" is measured, not asserted: a 1,020-run benchmark (17 scenarios = 14 synthetic + 3 seeded from an anonymized real portal, × 3 tool-surface arms × 4 trials, across five models from three vendors, deterministic graders over final CRM state, τ-bench-style pass^k) shows the gated CLI surface beating raw CRM-API access on completion-under-policy for every model tested — and the tool-surface effect is monotonic and vendor-independent. Full matrix and methodology: [the leaderboard](./evals/crm/leaderboard/RESULTS.md).
+
+The design is **deterministic apply, governed suggest**: the parts that touch your CRM — the audit rules, the plan/apply contract, compare-and-set, the survivor/merge logic — are deterministic and replayable; the parts that read free text (`call parse`/`score`, `market classify`) are LLM-powered but bounded, with every quoted span mechanically verified against the source before it can drive a writeback. Nondeterministic suggestion, deterministic governance.
 
 ## Authentication: CLI-first, browser only at the consent moment
 
@@ -269,6 +271,20 @@ A direct `login hubspot` always wins over a broker pairing, so an operator can o
 
 What each provider actually requires before `audit --provider <name>` works on your data.
 
+### Connector capabilities
+
+Connectors differ in what the provider's API allows — stated up front so nothing surprises you mid-evaluation:
+
+| Operation | HubSpot | Salesforce | Stripe |
+| --- | --- | --- | --- |
+| Read / snapshot / audit | ✅ | ✅ | ✅ (read-only) |
+| Field writes (`set_field`, `clear_field`, `link_record`) | ✅ | ✅ | — |
+| `create_task` | ✅ | ✅ | — |
+| `archive_record` | ✅ | ✅ | — |
+| `merge_records` (`dedupe`) | ✅ | ❌ **not supported** | — |
+
+**Salesforce merge** has no REST resource — it exists only in the SOAP API / Apex (Lead, Contact, Account, Case; max 3 records). This connector refuses a Salesforce `merge_records` operation honestly rather than half-merging; on Salesforce, deduplicate in the UI (or via SOAP/Apex), or use `bulk-update --archive` for the non-survivors. Native Salesforce merge is tracked future work, not a silent gap.
+
 ### HubSpot: create a private app (~2 minutes, needs super-admin)
 
 1. In HubSpot: **Settings → Integrations → Private Apps → Create a private app.**

package/SECURITY.md

@@ -0,0 +1,82 @@
+# Security Policy
+
+fullstackgtm reads and writes live CRM data under the operator's own
+credentials. We take its security posture seriously and design the write path
+to fail closed. This document is the disclosure process and the trust model a
+security reviewer needs.
+
+## Reporting a vulnerability
+
+Email **security@fullstackgtm.com** with a description and, ideally, a
+reproduction. Please do not open a public issue for a security report. We aim
+to acknowledge within 3 business days and to ship a fix or mitigation before
+any public disclosure. There is no bounty program yet; credit is given in the
+changelog unless you prefer otherwise.
+
+Supported version: the latest published `0.x` release on npm. Fixes land on the
+newest version, not backported (the project is pre-1.0).
+
+## Trust model
+
+**Credentials.** API tokens are never accepted as command-line arguments
+(they would leak into the process table and shell history); they come from an
+environment variable or stdin only, and are stored `0600` under a `0700` home
+(`$FSGTM_HOME`, default `~/.fullstackgtm`), re-tightened on read. This is the
+same custody model as the `gcloud`/`aws` CLIs. The hosted broker
+(`login --via`) exists so a team can connect a CRM once, server-side, and hand
+laptops only a revocable pairing token instead of a long-lived super-admin key;
+the broker URL must be https (cleartext is refused except for localhost dev).
+
+**OS keychain (opt-in).** Set `FSGTM_KEYCHAIN=1` to store the credential blob
+in the OS secret store instead of a plaintext file — macOS Keychain (via
+`security`) or Linux libsecret (via `secret-tool`); no native dependency. When
+enabled, a pre-existing `credentials.json` is migrated into the keychain and the
+plaintext file is removed, so a cloned home or restored backup finds no token at
+rest. Caveat: on macOS, `security add-generic-password` only accepts the secret
+via an argv flag, so it is briefly visible to a same-user `ps` during the write
+— a transient exposure strictly smaller than a persistent plaintext file, but a
+real one (Linux `secret-tool` reads the secret from stdin, with no such window).
+Backups or clones taken *before* enabling keychain already captured the file;
+rotate those credentials if that is a concern.
+
+**Writes are approval-gated.** Reads are safe by default. Every change is a
+typed patch operation in a dry-run plan that a human must approve before
+`apply`. `apply` writes only operations whose ids were explicitly approved,
+refuses operations carrying unresolved placeholder values, and uses
+compare-and-set against the live CRM so a value that drifted since the plan was
+built becomes a conflict, not a clobber. Irreversible operations (merge,
+archive) get a fresh-snapshot drift guard, and archiving a record that still
+shares an identity key with another is refused (it's a duplicate — merge it).
+
+**Approval integrity.** At approval time each operation's apply-relevant content
+is HMAC-signed with a per-install key (`$FSGTM_HOME/.plan-signing-key`, `0600`).
+`apply --plan-id` re-verifies; a plan edited after approval — by a synced copy,
+another process, or a compromised dependency — is refused rather than executed.
+The invariant: **what gets written equals what the human signed.** A plan
+approved on one machine cannot be applied on another (the key does not travel).
+Documented boundary: this defends the plan file, not an attacker who already
+holds the signing key (same directory and permissions as the credential store).
+
+**Scheduling never auto-approves.** Scheduled (cron) runs are restricted to a
+read/plan-side allowlist plus `apply --plan-id` whose approved status and
+signatures are re-checked at every firing. Arbitrary shell is not schedulable.
+
+**Untrusted input.** Competitor pages fetched by `market capture` are guarded
+against SSRF (scheme allowlist; private/loopback/link-local/metadata addresses
+refused; redirects re-validated). LLM-extracted call insights and market
+classifications are mechanically verified verbatim against the source text
+before they can drive a writeback, so a prompt-injected transcript or page
+cannot fabricate a grounded-looking change. CSV/formula-injection in ingested
+data is neutralized before it reaches a write.
+
+**Auditability.** `audit-log export` produces a hash-chained, install-signed
+record of every apply run for change-management/SIEM ingestion; `audit-log
+verify` detects any edit or reorder.
+
+## Data flows
+
+What leaves the machine, to whom, and for which command is enumerated in
+[DATA-FLOWS.md](./DATA-FLOWS.md). In brief: the core CLI is BYO-key and talks
+directly to your CRM and (only for LLM/enrichment verbs you invoke) to your
+chosen Anthropic/OpenAI/Apollo accounts — there is no fullstackgtm-operated
+data path for the open-source package.

package/dist/auditLog.d.ts

@@ -0,0 +1,58 @@
+import type { PatchPlanRun } from "./types.ts";
+import type { StoredPlan } from "./planStore.ts";
+/**
+ * Exportable, tamper-evident audit log.
+ *
+ * Every apply run is already recorded per-plan in the store, but a compliance /
+ * change-management process needs ONE portable artifact it can archive and
+ * later prove was not edited. `audit-log export` flattens every run across all
+ * plans into a hash-chained sequence: each entry carries the hash of the
+ * previous entry, so removing, reordering, or editing any entry breaks the
+ * chain at that point and `audit-log verify` reports exactly where. When a
+ * per-install signing key exists, the chain head is also HMAC-signed, so the
+ * export can be attributed to this installation, not just shown internally
+ * consistent.
+ *
+ * This is a point-in-time attestation of the stored run history; it is not a
+ * real-time append-only journal (that is future work). It answers "give me an
+ * auditable record of every change this tool applied, that my auditor can
+ * verify hasn't been doctored."
+ */
+export type AuditLogEntry = {
+    seq: number;
+    planId: string;
+    planTitle: string;
+    provider: string;
+    startedAt: string;
+    finishedAt: string;
+    status: PatchPlanRun["status"];
+    trigger: string;
+    /** operationId → status, the per-operation outcome of this run */
+    operations: Array<{
+        operationId: string;
+        status: string;
+        detail?: string;
+    }>;
+    prevHash: string;
+    hash: string;
+};
+export type AuditLogExport = {
+    version: 1;
+    generatedAt: string;
+    entryCount: number;
+    chainHead: string;
+    /** HMAC of chainHead with the per-install key, or null when no key exists. */
+    signature: string | null;
+    entries: AuditLogEntry[];
+};
+/** Flatten all runs from the stored plans, oldest first, into chained entries. */
+export declare function buildAuditLog(plans: StoredPlan[], generatedAt: string): AuditLogExport;
+export type AuditLogVerification = {
+    ok: boolean;
+    /** seq of the first entry whose hash does not verify, or null if the chain holds */
+    brokenAt: number | null;
+    signatureOk: boolean | null;
+    detail: string;
+};
+/** Recompute the chain (and the signature if a key is available). */
+export declare function verifyAuditLog(log: AuditLogExport): AuditLogVerification;

package/dist/auditLog.js

@@ -0,0 +1,112 @@
+import { createHash, createHmac } from "node:crypto";
+import { loadOrCreateSigningKey, loadSigningKey } from "./integrity.js";
+const GENESIS = "0".repeat(64);
+/** The content that the chain hash covers — everything but prevHash/hash. */
+function entryContent(entry) {
+    return JSON.stringify([
+        entry.seq,
+        entry.planId,
+        entry.planTitle,
+        entry.provider,
+        entry.startedAt,
+        entry.finishedAt,
+        entry.status,
+        entry.trigger,
+        entry.operations,
+    ]);
+}
+function chainHash(prevHash, content) {
+    return createHash("sha256").update(prevHash).update("\n").update(content).digest("hex");
+}
+/** Flatten all runs from the stored plans, oldest first, into chained entries. */
+export function buildAuditLog(plans, generatedAt) {
+    const runs = [];
+    for (const stored of plans) {
+        for (const run of stored.runs ?? [])
+            runs.push({ stored, run });
+    }
+    runs.sort((a, b) => a.run.finishedAt.localeCompare(b.run.finishedAt));
+    const entries = [];
+    let prevHash = GENESIS;
+    runs.forEach(({ stored, run }, index) => {
+        const base = {
+            seq: index,
+            planId: run.planId,
+            planTitle: stored.plan.title,
+            provider: run.provider,
+            startedAt: run.startedAt,
+            finishedAt: run.finishedAt,
+            status: run.status,
+            trigger: run.trigger ?? "manual",
+            operations: run.results.map((result) => ({
+                operationId: result.operationId,
+                status: result.status,
+                ...(result.detail ? { detail: result.detail } : {}),
+            })),
+        };
+        const hash = chainHash(prevHash, entryContent(base));
+        entries.push({ ...base, prevHash, hash });
+        prevHash = hash;
+    });
+    // Always sign — an unsigned export's keyless sha256 chain is self-recomputable
+    // (an attacker can edit entries and rebuild the chain from the public genesis),
+    // so the per-install HMAC is the only real tamper barrier. Bind the header
+    // fields into the signed material so metadata can't be altered either.
+    const key = loadOrCreateSigningKey();
+    const entryCount = entries.length;
+    return {
+        version: 1,
+        generatedAt,
+        entryCount,
+        chainHead: prevHash,
+        signature: signHead(key, 1, generatedAt, entryCount, prevHash),
+        entries,
+    };
+}
+function signHead(key, version, generatedAt, entryCount, chainHead) {
+    return createHmac("sha256", key).update(JSON.stringify([version, generatedAt, entryCount, chainHead])).digest("hex");
+}
+/** Recompute the chain (and the signature if a key is available). */
+export function verifyAuditLog(log) {
+    let prevHash = GENESIS;
+    for (const entry of log.entries) {
+        if (entry.prevHash !== prevHash) {
+            return { ok: false, brokenAt: entry.seq, signatureOk: null, detail: `Chain breaks at entry ${entry.seq}: prevHash does not match the previous entry's hash (an entry was removed, reordered, or edited).` };
+        }
+        const expected = chainHash(prevHash, entryContent(entry));
+        if (expected !== entry.hash) {
+            return { ok: false, brokenAt: entry.seq, signatureOk: null, detail: `Chain breaks at entry ${entry.seq}: its content was edited after export (hash mismatch).` };
+        }
+        prevHash = entry.hash;
+    }
+    if (prevHash !== log.chainHead) {
+        return { ok: false, brokenAt: log.entries.length, signatureOk: null, detail: "The recorded chainHead does not match the recomputed chain." };
+    }
+    // The keyless chain alone is self-recomputable, so a missing/stripped signature
+    // means the export is forgeable — refuse it. (Current exports are always
+    // signed; a null signature is an old/unsigned or a downgraded export.)
+    if (!log.signature) {
+        return {
+            ok: false,
+            brokenAt: null,
+            signatureOk: false,
+            detail: "Unsigned export: the hash chain alone is self-recomputable, so this log cannot be trusted (the signature is absent or was stripped). Re-export on the issuing install.",
+        };
+    }
+    const key = loadSigningKey();
+    if (!key) {
+        // A third party without the issuing install's key cannot verify attribution.
+        // The chain is internally consistent, but that is not proof of authenticity.
+        return {
+            ok: false,
+            brokenAt: null,
+            signatureOk: null,
+            detail: "Chain is internally consistent, but this machine has no signing key to verify the signature — authenticity is unattributed. Verify on the issuing install.",
+        };
+    }
+    const signatureOk = signHead(key, log.version, log.generatedAt, log.entryCount, prevHash) === log.signature;
+    if (!signatureOk) {
+        return { ok: false, brokenAt: null, signatureOk: false, detail: "Signature does not match this installation's key — the log was exported elsewhere, or its entries/metadata were altered after signing." };
+    }
+    return { ok: true, brokenAt: null, signatureOk: true, detail: `Verified ${log.entries.length} entries; chain intact and signature valid.` };
+}

package/dist/bulkUpdate.d.ts

@@ -33,10 +33,17 @@ export type BulkUpdateOptions = {
     reason?: string;
     /** refuse to build plans larger than this (default 500 operations) */
     maxOperations?: number;
+    /**
+     * Date the comparison `today` literal resolves to (ISO yyyy-mm-dd). Set from
+     * the policy/--today date at the CLI; defaults to the system date. Stored on
+     * plan.filter so apply-time filter re-verification resolves `today`
+     * identically to plan time.
+     */
+    today?: string;
 };
 type WhereClause = {
     field: string;
-    op: "eq" | "neq" | "contains" | "notcontains" | "empty" | "notempty";
+    op: "eq" | "neq" | "contains" | "notcontains" | "empty" | "notempty" | "lt" | "gt" | "lte" | "gte";
     value?: string;
     raw: string;
 };
@@ -44,9 +51,14 @@ export declare function parseWhere(expr: string): WhereClause;
 /** True when `field` is filterable for this object type (relational pseudo-fields included). */
 export declare function isFilterableField(objectType: BulkUpdateOptions["objectType"], field: string): boolean;
 export declare function parseGuard(raw: string): PlanGuard;
-/** Ids of records matching a filter — used for apply-time filter re-verification. */
-export declare function eligibleIds(snapshot: CanonicalGtmSnapshot, objectType: BulkUpdateOptions["objectType"], where: string[]): Set<string>;
+/**
+ * Ids of records matching a filter — used for apply-time filter
+ * re-verification. `today` resolves the comparison `today` literal; apply-time
+ * callers pass the value the plan was built with (stored on plan.filter.today)
+ * so re-verification uses the SAME today, defaulting to the system date.
+ */
+export declare function eligibleIds(snapshot: CanonicalGtmSnapshot, objectType: BulkUpdateOptions["objectType"], where: string[], today?: string): Set<string>;
 /** Evaluate a plan guard against a snapshot. Returns null when satisfied, else a failure detail. */
-export declare function evaluateGuard(snapshot: CanonicalGtmSnapshot, guard: PlanGuard): string | null;
+export declare function evaluateGuard(snapshot: CanonicalGtmSnapshot, guard: PlanGuard, today?: string): string | null;
 export declare function buildBulkUpdatePlan(snapshot: CanonicalGtmSnapshot, options: BulkUpdateOptions): PatchPlan;
 export {};