@tacuchi/agent-workflow-cli 25.4.0 → 25.6.0

package/README.md

@@ -187,6 +187,8 @@ Workspace artifacts live under `.<namespace>/`. Resolution order (first match wi
 - `self install-skill` / `self doctor` / `self update` / `mcp` — CLI maintenance.
 - `amend <apply|revert|list>` — correct the WORDING of an already closed spec or plan in one act, under the workspace lock and with the document's own digest as the compare-and-swap base; it demands an explicit declaration that no scope, criteria or rules move, records the exact pre-image in an append-only ledger, and refuses structurally whatever touches the contract (naming the refinement instead). CLI-only: there is no `/w:amend`.
 - `settle <list|prepare|apply>` — settle or acknowledge the live obligations a decision note left on a plan whose execution run is already closed. `list` shows each one with its note, position, class, whether that class was declared and the plan's CURRENT resume point; `prepare` derives the same settlement note the closure derives, writes nothing and returns the digest that authorizes it; `apply` re-derives from the live workspace, demands that digest and publishes under the lock. It refuses while an execution run holds the plan, naming that run — its closure settles its own obligations. CLI-only: there is no `/w:settle`.
+- `cut-intent <declare|show>` — the intention with which a spec cut into several plans was meant to be executed: which plans travel together in one pass, in what order, and which are deferred with their cause. Correcting means declaring again — the previous record stays legible underneath, so a reordering is something a person can review instead of simply inherit. It restricts nothing: executing out of the declared order stays valid and is only warned. CLI-only: there is no `/w:cut-intent`.
+- `release-pass <list|declare|arrived|applied|revert|link>` — the pass to production as its own object, because closed is not released. `declare` opens one over the sources it covers; `arrived` registers one source's arrival, and while another is still missing the pass reads partially released, naming both; `applied` registers that the SQL the pass carries RAN against a named environment — its own axis, never a fourth arrival kind, so a pass with no such record reads NO RECORD rather than nothing-applied; `revert` adds a reversion that never erases the arrivals it follows; `link` attaches a document by workspace-relative path, checking only that it exists. Nothing here checks the world: registering is DECLARING a fact somebody already knows. It feeds the `production` axis of `status`/`resume` and the `--environment` filter of `export-scripts`. CLI-only: there is no `/w:release-pass`.
 
 Run `agent-workflow --help` (or `aw --help`) for the full list, or `agent-workflow <command> --help` for per-command flags.
 

package/dist/application/cut-intent-ledger.js

@@ -0,0 +1,164 @@
+/**
+ * The durable record of how somebody meant to execute a cut — and the only place
+ * it lives.
+ *
+ * Same shape and same reasons as the claims ledger next to it: append-only, one
+ * JSON record per line, under `.workflow/` and deliberately OUTSIDE `docs/`. The
+ * corpus is for documents somebody published; an intent is workspace state, not a
+ * document, and putting it in `docs/` would make the record itself look like a
+ * spec or a plan.
+ *
+ * Append-only is load-bearing for a different reason here than there. A
+ * revocation has to be irrevocable; an intent, by contrast, is *meant* to be
+ * corrected — plans get reordered, a group gets split, something moves to the
+ * next pass. So a correction is a NEW record that supersedes the previous one
+ * for reading, and the previous one stays exactly where it was. Rewriting it
+ * would destroy the one thing that makes a reorder reviewable: what the order
+ * used to be, and therefore that somebody changed it.
+ */
+import { join } from "node:path";
+import { assertDeclarable, positionOf, } from "../domain/cut-intent.js";
+import { formatNodeId, isWorklineKind } from "../domain/workline-node.js";
+/** Lives next to HISTORY.md and claims.jsonl: workspace state, never corpus. */
+const LEDGER_FILE = "cut-intents.jsonl";
+const LEDGER_VERSION = 1;
+export function cutIntentLedgerPath(paths) {
+    return join(paths.cwdRoot(), LEDGER_FILE);
+}
+/**
+ * Add one record. Append-only by construction: there is no update and no delete.
+ *
+ * Validated before the write for the reason the whole file exists: a malformed
+ * record cannot be corrected in place, only buried, so the cheap refusal is here.
+ * One record is one short line, so `O_APPEND` keeps concurrent writers from
+ * interleaving halves of it — the same bound the claims ledger relies on, and the
+ * same reason a record is not pretty-printed.
+ */
+export async function appendCutIntent(fs, paths, event) {
+    assertDeclarable(event.intent);
+    const record = { version: LEDGER_VERSION, event: "declared", ...event };
+    await fs.appendText(cutIntentLedgerPath(paths), `${JSON.stringify(record)}\n`);
+}
+/** Every record, oldest first. A missing ledger reads as empty, never as an error. */
+export async function readCutIntents(fs, paths) {
+    const path = cutIntentLedgerPath(paths);
+    if (!(await fs.exists(path)))
+        return { events: [], unreadable: 0 };
+    const raw = await fs.readText(path);
+    const events = [];
+    let unreadable = 0;
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        const parsed = parseEvent(trimmed);
+        if (parsed === null)
+            unreadable += 1;
+        else
+            events.push(parsed);
+    }
+    return { events, unreadable };
+}
+function parseEvent(line) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (typeof value !== "object" || value === null)
+        return null;
+    const candidate = value;
+    if (typeof candidate.at !== "string" || candidate.event !== "declared")
+        return null;
+    const intent = candidate.intent;
+    if (typeof intent !== "object" || intent === null)
+        return null;
+    if (!isNode(intent.spec) || !isNodeList(intent.order) || !isNodeList(intent.deferred)) {
+        return null;
+    }
+    return value;
+}
+function isNode(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const node = value;
+    return isWorklineKind(node.kind) && typeof node.key === "string" && node.key.length > 0;
+}
+function isNodeList(value) {
+    return Array.isArray(value) && value.every(isNode);
+}
+/**
+ * The intent in force for this spec: the LAST record about it, or `null`.
+ *
+ * Derived rather than stored, because the ledger is append-only and a "current"
+ * flag would be exactly the mutable state that makes an append-only log
+ * pointless. Last-wins is the whole correction mechanism: declaring again is how
+ * you fix an order, and the superseded record stays readable above it.
+ */
+export function currentIntentOf(events, spec) {
+    const key = formatNodeId(spec);
+    let current = null;
+    for (const event of events) {
+        if (formatNodeId(event.intent.spec) === key)
+            current = event;
+    }
+    return current;
+}
+/**
+ * The intent in force that mentions this plan, or `null`.
+ *
+ * Asked by plan rather than by spec because that is the question the board has:
+ * it is holding a plan and wants to know where the person put it. A plan is
+ * mentioned by at most one cut in force — its spec's — so the first match is the
+ * answer, and a plan named by a superseded record only counts if the record that
+ * superseded it still names it.
+ */
+export function currentIntentForPlan(events, plan) {
+    const specs = new Set(events.map((event) => formatNodeId(event.intent.spec)));
+    const key = formatNodeId(plan);
+    for (const spec of specs) {
+        const [kind, ...rest] = spec.split(":");
+        if (!isWorklineKind(kind))
+            continue;
+        const current = currentIntentOf(events, { kind, key: rest.join(":") });
+        if (current === null)
+            continue;
+        const mentioned = [...current.intent.order, ...current.intent.deferred].some((node) => formatNodeId(node) === key);
+        if (mentioned)
+            return current;
+    }
+    return null;
+}
+/**
+ * What the workspace answers about one plan — the explicit reading, never a list.
+ *
+ * The `declared: false` branch carries its reason because the three ways a plan
+ * can have no declared place are not the same thing to the person reading it:
+ * nobody ever declared a cut for its spec, the ledger could not be fully read, or
+ * a cut exists and simply does not mention this plan. Collapsing them into an
+ * empty list is what would let a caller fill the silence with the correlative.
+ */
+export function readingForPlan(read, plan) {
+    const current = currentIntentForPlan(read.events, plan);
+    if (current === null) {
+        if (read.unreadable > 0) {
+            return {
+                declared: false,
+                reason: `no hay intención declarada legible para '${formatNodeId(plan)}': el libro tiene ${read.unreadable} línea(s) que no se pueden leer, así que su ausencia no está probada`,
+            };
+        }
+        return {
+            declared: false,
+            reason: `nadie declaró una intención de corte que nombre a '${formatNodeId(plan)}'`,
+        };
+    }
+    return {
+        declared: true,
+        intent: current.intent,
+        at: current.at,
+        position: positionOf(current.intent, plan),
+    };
+}
+//# sourceMappingURL=cut-intent-ledger.js.map

package/dist/application/cut-intent-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cut-intent-ledger.js","sourceRoot":"","sources":["../../src/application/cut-intent-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAGL,gBAAgB,EAChB,UAAU,GACX,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAuB,YAAY,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAI/F,gFAAgF;AAChF,MAAM,WAAW,GAAG,mBAAmB,CAAC;AACxC,MAAM,cAAc,GAAG,CAAC,CAAC;AAYzB,MAAM,UAAU,mBAAmB,CAAC,KAAmB;IACrD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,WAAW,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,EAAkB,EAClB,KAAmB,EACnB,KAAgD;IAEhD,gBAAgB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,MAAM,MAAM,GAAmB,EAAE,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,KAAK,EAAE,CAAC;IACxF,MAAM,EAAE,CAAC,UAAU,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACjF,CAAC;AAeD,sFAAsF;AACtF,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,EAAkB,EAClB,KAAmB;IAEnB,MAAM,IAAI,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACxC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC;IACnE,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,MAAM,GAAqB,EAAE,CAAC;IACpC,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACnC,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,MAAM,KAAK,IAAI;YAAE,UAAU,IAAI,CAAC,CAAC;;YAChC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;AAChC,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC9B,IAAI,KAAc,CAAC;IACnB,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC7D,MAAM,SAAS,GAAG,KAAgC,CAAC;IACnD,IAAI,OAAO,SAAS,CAAC,EAAE,KAAK,QAAQ,IAAI,SAAS,CAAC,KAAK,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IACpF,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC;IAChC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/D,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAuB,CAAC;AACjC,CAAC;AAED,SAAS,MAAM,CAAC,KAAc;IAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,IAAI,GAAG,KAAgC,CAAC;IAC9C,OAAO,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;AAC1F,CAAC;AAED,SAAS,UAAU,CAAC,KAAc;IAChC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAiC,EACjC,IAAoB;IAEpB,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,OAAO,GAA0B,IAAI,CAAC;IAC1C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,GAAG;YAAE,OAAO,GAAG,KAAK,CAAC;IAC/D,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAiC,EACjC,IAAoB;IAEpB,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9E,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;YAAE,SAAS;QACpC,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACvE,IAAI,OAAO,KAAK,IAAI;YAAE,SAAS;QAC/B,MAAM,SAAS,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAC1E,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,GAAG,CACrC,CAAC;QACF,IAAI,SAAS;YAAE,OAAO,OAAO,CAAC;IAChC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,IAAmB,EAAE,IAAoB;IACtE,MAAM,OAAO,GAAG,oBAAoB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACxD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,IAAI,IAAI,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;YACxB,OAAO;gBACL,QAAQ,EAAE,KAAK;gBACf,MAAM,EAAE,4CAA4C,YAAY,CAAC,IAAI,CAAC,qBAAqB,IAAI,CAAC,UAAU,sEAAsE;aACjL,CAAC;QACJ,CAAC;QACD,OAAO;YACL,QAAQ,EAAE,KAAK;YACf,MAAM,EAAE,sDAAsD,YAAY,CAAC,IAAI,CAAC,GAAG;SACpF,CAAC;IACJ,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,QAAQ,EAAE,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC;KAC3C,CAAC;AACJ,CAAC"}

package/dist/application/export-service.js

@@ -1,9 +1,12 @@
+import { basename, relative, sep } from "node:path";
 import { CORRELATIVE_SOURCE, isCorrelative } from "../domain/correlative.js";
 import { localDateIso } from "./dates.js";
 import { runNextNumber } from "./dev-only-services.js";
 import { resolveDocsCanon } from "./docs-canon-service.js";
+import { appendPublications, publicationRows } from "./history-publications.js";
 import { withCwdLock } from "./lock-service.js";
 import { runReleaseData } from "./release-data-service.js";
+import { derivePasses, readReleasePasses } from "./release-pass-ledger.js";
 import { approvalDigest, buildSemanticRequest, parseSemanticResponse, readEnvelopeScope, } from "./semantic-operation/protocol.js";
 import { publishArtifacts } from "./semantic-operation/publish.js";
 export const EXPORT_CATEGORIES = [
@@ -17,11 +20,12 @@ export const EXPORT_CATEGORIES = [
  * command guide. Keep its semantic anchors exported so a small parity guard
  * catches doctrine that drifts away from what the CLI actually sends.
  */
-export const SCRIPTS_FINAL_STATE_CONTRACT = "Un dossier con 00-ROLLBACK.sql y README.md obligatorios, más los forwards NN-<nombre>.sql numerados de forma continua desde 01. El CLI NUNCA ejecuta SQL. El bundle publica el ESTADO FINAL NETO de la secuencia, no una réplica por sesión: lo que nace y muere dentro de la secuencia se omite; lo migrado va directo a su forma final; lo que el contexto declara retirado se omite aunque ningún script lo elimine. 00-ROLLBACK.sql invierte ese ESTADO FINAL en orden seguro para las dependencias, no el reverso literal de los forwards. Reconciliá contra el código además de las sesiones y la base. Excluí identidades concretas y semillas de prueba; conservá sólo objetos compartidos y necesarios para el estado final.";
+export const SCRIPTS_FINAL_STATE_CONTRACT = "Un dossier con 00-ROLLBACK.sql y README.md obligatorios, más los forwards NN-<nombre>.sql numerados de forma continua desde 01. El CLI NUNCA ejecuta SQL. El bundle publica el ESTADO FINAL NETO de la secuencia, no una réplica por sesión: lo que nace y muere dentro de la secuencia se omite; lo migrado va directo a su forma final; lo que el contexto declara retirado se omite aunque ningún script lo elimine. 00-ROLLBACK.sql invierte ese ESTADO FINAL en orden seguro para las dependencias, no el reverso literal de los forwards. Reconciliá contra el código además de las sesiones y la base. Excluí identidades concretas y semillas de prueba; conservá sólo objetos compartidos y necesarios para el estado final. Un bundle previo que entra al origen es MATERIAL A RECONCILIAR, no historia intocable: dos bundles que se contradicen publican el estado final neto resultante, nunca su suma cronológica.";
 export const SCRIPTS_FINAL_STATE_CONTRACT_ANCHORS = [
     "ESTADO FINAL NETO",
     "orden seguro para las dependencias",
     "objetos compartidos y necesarios para el estado final",
+    "MATERIAL A RECONCILIAR",
 ];
 const POLICIES = {
     diagrams: {
@@ -57,6 +61,7 @@ const POLICIES = {
 };
 const LIMITS = { max_artifacts: 64, max_artifact_bytes: 512 * 1024 };
 const FORWARD_RE = /^(\d{2})-[^/]+\.sql$/;
+const EXPORT_BASES = ["sessions", "bundles", "workspace"];
 // ── prepare ──────────────────────────────────────────────────────────────────
 export async function prepareExport(fs, env, paths, category, selection = {}, 
 // Injected so the midnight boundary is testable: a preparation that outlives
@@ -74,27 +79,10 @@ now = () => new Date()) {
         };
     }
     const policy = resolvePolicy(category, canon.canon[category]);
-    const corpus = await readCorpus(fs, env, paths, selection);
-    if ("error" in corpus) {
-        return {
-            ok: false,
-            failure: {
-                code: "EXPORT_CORPUS_UNAVAILABLE",
-                message: corpus.error,
-                action: "revisá el workspace y los filtros --sessions/--since/--source",
-            },
-        };
-    }
-    if (corpus.sessions.length === 0) {
-        return {
-            ok: false,
-            failure: {
-                code: "EXPORT_CORPUS_EMPTY",
-                message: "ninguna sesión coincide con los filtros",
-                action: "ampliá --since, quitá --sessions, o revisá que existan sesiones cerradas",
-            },
-        };
-    }
+    const resolved = await resolveMaterial(fs, env, paths, category, selection);
+    if (!resolved.ok)
+        return resolved;
+    const material = resolved.value;
     // Pinned when the answer echoed them, derived only on a first preparation:
     // re-deriving either at `validate` renames the very unit the answer wrote to,
     // and neither is workspace state that a stale check should be defending.
@@ -120,6 +108,9 @@ now = () => new Date()) {
         ...(selection.sessions !== undefined ? { sessions: selection.sessions } : {}),
         ...(selection.since !== undefined ? { since: selection.since } : {}),
         ...(selection.source !== undefined ? { source: selection.source } : {}),
+        ...(selection.from !== undefined ? { from: selection.from } : {}),
+        ...(selection.exclude !== undefined ? { exclude: selection.exclude } : {}),
+        ...(selection.environment !== undefined ? { environment: selection.environment } : {}),
         date,
         next,
     };
@@ -130,18 +121,34 @@ now = () => new Date()) {
         required: policy.required,
         extensions: policy.extensions,
         overwritable: policy.overwritable,
-        sessions: corpus.sessions,
+        // What the material was composed from, and what stayed in and out of it —
+        // declared BEFORE anything is composed, which is the only moment at which
+        // the person can still disagree with the origin.
+        origins: material.origins,
+        sessions: material.sessions,
+        bundles: material.bundles,
+        standalone_sql: material.standalone,
+        excluded: material.excluded,
+        exclude_unmatched: material.unmatched,
+        environment: material.environment,
         date,
     };
-    const readSet = corpus.sessions.map((s) => s.path ?? s.folder);
+    const readSet = materialPaths(material);
     const request = buildSemanticRequest({
         operation: `export-${category}`,
-        // What the seal defends is workspace state: the corpus the scope covers (a
-        // session appearing or closing changes what the dossier should have
-        // contained) and the folder this workspace publishes to. The scope rides
-        // along so an altered echo cannot pass as the original one.
-        inputs: { corpus: corpus.sessions, dir: policy.dir, scope },
-        sealed: "el corpus de sesiones del alcance o el destino declarado de la categoría",
+        // What the seal defends is workspace state: the MATERIAL the scope covers —
+        // sessions, loose SQL and previously published bundles alike, since any of
+        // them appearing or changing changes what the dossier should have contained
+        // — and the folder this workspace publishes to. The scope rides along so an
+        // altered echo cannot pass as the original one.
+        inputs: {
+            corpus: material.sessions,
+            bundles: material.bundles,
+            standalone: material.standalone,
+            dir: policy.dir,
+            scope,
+        },
+        sealed: "el material del alcance o el destino declarado de la categoría",
         scope,
         contract: `${policy.contract} Respondé artifacts con paths dentro de ${unit}${policy.overwritable === null ? "" : ` (o exactamente ${policy.overwritable})`}. El NNN es consultivo: el CLI reasigna el número dentro del lock. Copiá 'scope' TAL CUAL en tu respuesta: validate y apply lo leen en vez de re-derivarlo.`,
         inventory,
@@ -162,12 +169,104 @@ function resolvePolicy(category, dir) {
         overwritable: overwritable === undefined ? null : `${resolved}/${overwritable}`,
     };
 }
-async function readCorpus(fs, env, paths, selection) {
+/**
+ * The composable origin belongs to the SQL bundle and to nothing else.
+ *
+ * The other three categories publish documents an author writes; there is no
+ * previous manual to re-consolidate and no environment a diagram ran against.
+ * Accepting the flags there would answer a question those categories never ask.
+ */
+function checkComposableSelection(category, selection) {
+    // Belonging comes FIRST: telling a category that does not compose its origin
+    // which bases exist would send it to fix a value that was never going to be
+    // read, and it would be rejected again on the next invocation.
+    const named = ["from", "exclude", "environment"].filter((key) => selection[key] !== undefined);
+    if (category !== "scripts" && named.length > 0) {
+        return {
+            code: "EXPORT_SCOPE_INVALID",
+            message: `${named.map((k) => `--${k}`).join(", ")} es del bundle de SQL: export-${category} parte siempre del corpus de sesiones`,
+            action: "quitá esos flags, o usá aw export-scripts si lo que querés componer es el bundle",
+        };
+    }
+    // Rejected HERE and not when the base is read, for the same reason a malformed
+    // `--date` is: the invocation that supplied it is the one that can fix it, and
+    // an unknown base silently read as one of the three would compose a different
+    // origin than the one that was asked for.
+    if (selection.from !== undefined && !EXPORT_BASES.includes(selection.from)) {
+        return {
+            code: "EXPORT_SCOPE_INVALID",
+            message: `--from '${selection.from}' no es una base: ${EXPORT_BASES.join(", ")}`,
+            action: "repetí la invocación con una de las tres bases, o sin --from para partir de las sesiones",
+        };
+    }
+    return null;
+}
+/**
+ * The material this preparation covers, or the reason there is none.
+ *
+ * The three ways it can fail — a base that is not one, an origin this category
+ * does not compose, and an origin that came back empty — answer the same
+ * question and travel together, so `prepare` reads as the sequence it is.
+ */
+async function resolveMaterial(fs, env, paths, category, selection) {
+    const invalid = checkComposableSelection(category, selection);
+    if (invalid !== null)
+        return { ok: false, failure: invalid };
+    const material = await composeMaterial(fs, env, paths, selection);
+    if ("error" in material) {
+        return {
+            ok: false,
+            failure: {
+                code: "EXPORT_CORPUS_UNAVAILABLE",
+                message: material.error,
+                action: "revisá el workspace y los filtros --sessions/--since/--source",
+            },
+        };
+    }
+    if (materialCount(material) === 0)
+        return { ok: false, failure: emptyOrigin(material) };
+    return { ok: true, value: material };
+}
+/**
+ * Why the origin came back empty — and "everything already ran" is its own answer.
+ *
+ * Proposing a bundle with nothing in it would be the wrong outcome twice over:
+ * there is nothing to deliver, and the reason there is nothing is good news the
+ * person asked for. Folding it into the generic empty corpus would send them
+ * looking for a filter to widen.
+ */
+function emptyOrigin(material) {
+    const applied = material.excluded.filter((item) => item.reason === "applied");
+    if (applied.length > 0 && material.environment !== null) {
+        return {
+            code: "EXPORT_ORIGIN_ALREADY_APPLIED",
+            message: `todo el material que quedaba en el origen ya consta aplicado en '${material.environment.name}': no hay nada que consolidar`,
+            action: `nada que hacer; si igual querés reconsolidarlo, repetí la invocación sin --environment ${material.environment.name}`,
+        };
+    }
+    return {
+        code: "EXPORT_CORPUS_EMPTY",
+        message: `ningún material del origen (${material.origins.join(", ")}) coincide con los filtros`,
+        action: "ampliá --since, quitá --sessions o --exclude, probá otro --from, o revisá que existan sesiones cerradas",
+    };
+}
+/**
+ * The material of this preparation: a base brings, the exclusions subtract.
+ *
+ * Both halves in one place, because "where did this come from" and "why is this
+ * not here" are the two questions `prepare` has to answer together — and the
+ * listings the bases read are the ones `release-data` already produces, walked
+ * once by it rather than twice by this.
+ */
+async function composeMaterial(fs, env, paths, selection) {
+    const base = selection.from ?? "sessions";
     const input = {
         includeClosed: true,
-        // Graduated bundles are previous exports: re-exporting them would duplicate
-        // what already lives in docs/.
-        includeGraduated: false,
+        // A base of `sessions` is the behavior that always was: graduated bundles are
+        // previous exports and re-exporting them would duplicate what already lives
+        // in docs/. The other bases are asking for exactly that material.
+        includeGraduated: base !== "sessions",
+        includeStandaloneSql: base === "workspace",
         ...(selection.sessions !== undefined ? { sessions: selection.sessions } : {}),
         ...(selection.since !== undefined ? { since: selection.since } : {}),
         ...(selection.source !== undefined ? { sourceAlias: selection.source } : {}),
@@ -175,7 +274,104 @@ async function readCorpus(fs, env, paths, selection) {
     const data = await runReleaseData(fs, env, paths, input);
     if ("error" in data)
         return { error: data.error };
-    return { sessions: data.sessions };
+    const sessions = base === "bundles" ? [] : data.sessions;
+    const standalone = base === "workspace" ? (data.standalone_sql ?? []) : [];
+    const bundles = base === "sessions" ? [] : (data.graduated_bundles ?? []);
+    const origins = [
+        ...(base === "bundles" ? [] : ["sessions"]),
+        ...(base === "workspace" ? ["standalone-sql"] : []),
+        ...(base === "sessions" ? [] : ["bundles"]),
+    ];
+    const named = new Set(selection.exclude ?? []);
+    const manual = [
+        ...sessions.map((s) => piece("sessions", s.folder, s.path ?? s.folder)),
+        ...standalone.map((f) => piece("standalone-sql", f.name, f.path)),
+        ...bundles.map((b) => piece("bundles", bundleName(b), b.path)),
+    ]
+        .filter((item) => named.has(item.name))
+        .map((item) => ({ ...item, reason: "manual" }));
+    // A name that subtracted nothing is DECLARED, not rejected: the base or the
+    // filters may have left that piece out already, and refusing an invocation
+    // whose intent is served would be hostile. But a typo looks identical from
+    // here, and staying silent would ship the very material the person believed
+    // they had taken out — which is the failure this whole command exists against.
+    const matched = new Set(manual.map((item) => item.name));
+    const unmatched = [...named].filter((name) => !matched.has(name));
+    // The environment subtracts from what the manual exclusions already left, and
+    // by the SAME road: both are exclusions of pieces and differ only in the
+    // reason the inventory declares, which is the whole of D-05.
+    const kept = bundles.filter((b) => !named.has(bundleName(b)));
+    const environment = await filterByEnvironment(fs, paths, selection.environment, kept);
+    const excluded = [...manual, ...environment.excluded];
+    const out = new Set(excluded.map((item) => item.name));
+    return {
+        origins,
+        sessions: sessions.filter((s) => !out.has(s.folder)),
+        bundles: bundles.filter((b) => !out.has(bundleName(b))),
+        standalone: standalone.filter((f) => !out.has(f.name)),
+        excluded,
+        unmatched,
+        environment: environment.filter,
+    };
+}
+/**
+ * Which of these bundles the book says already ran against this environment.
+ *
+ * The chain adds no new piece: a pass LINKS the bundle by workspace-relative
+ * path and that same pass has an application for the environment. One record is
+ * enough — a bundle linked to two passes where only one ran there did run, and
+ * demanding unanimity would re-deliver SQL that is already in place, which is
+ * the error this filter exists to prevent.
+ */
+async function filterByEnvironment(fs, paths, environment, bundles) {
+    if (environment === undefined)
+        return { excluded: [], filter: null };
+    const passes = derivePasses((await readReleasePasses(fs, paths)).events);
+    const there = passes.filter((derived) => derived.application.axis === "applied" &&
+        derived.application.environments.includes(environment));
+    // Both sides normalized to `/`: the book stores the path a person typed and
+    // this one comes from the filesystem, so on Windows the same bundle would be
+    // `docs/scripts/…` in one and `docs\\scripts\\…` in the other and nothing would
+    // ever match — every bundle would read as pending and be delivered twice.
+    const linked = new Set(there.flatMap((derived) => derived.artifacts).map(slashed));
+    const excluded = bundles
+        .filter((bundle) => linked.has(slashed(relative(paths.workspaceDir(), bundle.path))))
+        .map((bundle) => ({
+        ...piece("bundles", bundleName(bundle), bundle.path),
+        reason: "applied",
+    }));
+    return {
+        excluded,
+        filter: {
+            name: environment,
+            axis: there.length === 0 ? "no-record" : "applied",
+            scanned: bundles.length,
+            excluded: excluded.length,
+        },
+    };
+}
+/** One spelling for a path that two different producers wrote. */
+function slashed(path) {
+    return path.split(sep).join("/");
+}
+/** What names a bundle in `--exclude` and in the inventory: its directory. */
+function bundleName(bundle) {
+    return basename(bundle.path);
+}
+function piece(origin, name, path) {
+    return { origin, name, path };
+}
+/** How many pieces stayed in. Zero is an empty origin, whatever the base was. */
+function materialCount(material) {
+    return material.sessions.length + material.bundles.length + material.standalone.length;
+}
+/** Everything the composer has to read, across the three origins. */
+function materialPaths(material) {
+    return [
+        ...material.sessions.map((s) => s.path ?? s.folder),
+        ...material.standalone.map((f) => f.path),
+        ...material.bundles.map((b) => b.path),
+    ];
 }
 // ── the scope, travelling between stages ─────────────────────────────────────
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
@@ -205,6 +401,9 @@ export function readExportScope(raw) {
             ...(scope.sessions !== undefined ? { sessions: scope.sessions } : {}),
             ...(scope.since !== undefined ? { since: scope.since } : {}),
             ...(scope.source !== undefined ? { source: scope.source } : {}),
+            ...(scope.from !== undefined ? { from: scope.from } : {}),
+            ...(scope.exclude !== undefined ? { exclude: scope.exclude } : {}),
+            ...(scope.environment !== undefined ? { environment: scope.environment } : {}),
             date: scope.date,
             next: scope.next,
         },
@@ -221,7 +420,13 @@ function scopeShapeError(scope) {
     if (scope.sessions !== undefined && !isStringArray(scope.sessions)) {
         return "'sessions' tiene que ser una lista de códigos de texto";
     }
-    for (const key of ["since", "source"]) {
+    if (scope.exclude !== undefined && !isStringArray(scope.exclude)) {
+        return "'exclude' tiene que ser una lista de nombres de texto";
+    }
+    if (scope.from !== undefined && !EXPORT_BASES.includes(scope.from)) {
+        return `'from' tiene que ser ${EXPORT_BASES.join(", ")}`;
+    }
+    for (const key of ["since", "source", "environment"]) {
         if (scope[key] !== undefined && typeof scope[key] !== "string") {
             return `'${key}' tiene que ser texto`;
         }
@@ -255,10 +460,15 @@ export function conflictingScopeFlags(echoed, flags) {
     if (flags.sessions !== undefined && !same(flags.sessions, echoed.sessions)) {
         conflicts.push("--sessions");
     }
+    if (flags.exclude !== undefined && !same(flags.exclude, echoed.exclude)) {
+        conflicts.push("--exclude");
+    }
     for (const [flag, key] of [
         ["--since", "since"],
         ["--source", "source"],
         ["--date", "date"],
+        ["--from", "from"],
+        ["--environment", "environment"],
     ]) {
         if (flags[key] !== undefined && flags[key] !== echoed[key])
             conflicts.push(flag);
@@ -367,9 +577,15 @@ export async function applyExport(fs, env, paths, input) {
         const artifacts = (parsed.value.artifacts ?? []).map((artifact) => renumber(artifact, input.prepared, minted, policy));
         // Whole dossier or nothing: `publishArtifacts` restores every previous
         // state on the first failure.
-        return await publishArtifacts(fs, paths.workspaceDir(), artifacts, {
+        const published = await publishArtifacts(fs, paths.workspaceDir(), artifacts, {
             overwrite: input.allowOverwrite === true,
         });
+        // Under the SAME lock as the write, for the same reason as in `persist`: two
+        // concurrent publications outside it would lose one of the two rows.
+        if (published.ok) {
+            await appendPublications(fs, paths.cwdHistoryFile(), publicationRows(published.value.written, `export-${input.prepared.category}`));
+        }
+        return published;
     });
     if ("error" in result) {
         return {