pi-aia-asf 0.13.1 → 0.13.3

package/CHANGELOG.md

@@ -7,6 +7,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.3] - 2026-10-16
+
+### Fixed
+
+- **06j §5 had drifted back into enumerating products.** The section now carries
+  the store-agnostic *rule* — the defect is not SQL-shaped, and the distinction
+  that makes a hand-written cascade decidable is the **reference** (a row removing
+  itself vs one entity deciding the fate of another) — instead of a table of
+  store families and a list of ORM dialects. Which dialects the scanner
+  recognises is an implementation detail in `lib/code-health/model.mjs`, reported
+  per finding so you can see what it looked at; the standard states categories and
+  leaves the rest to `model.extraCascadePatterns` /
+  `model.extraHandWrittenPatterns`. A recognised dialect is not a coverage
+  promise: an unknown persistence shape is a `scanned: 0` you say out loud, not a
+  clean bill of health. The fixtures keep naming the concrete dialects — that is
+  where a pattern set belongs.
+
+## [0.13.2] - 2026-10-16
+
+### Added
+
+- **The model gate is now store-agnostic in fact, not just in intent.** It knew
+  SQL DDL and ORM cascade spellings and nothing else, so in a document, key-value,
+  wide-column or search store — where there is no constraint to declare a cascade
+  in — the gate was blind to the exact defect it exists to catch. A third rule,
+  `handwritten-cascade`, catches the cascade that exists only as code someone
+  wrote: a multi-delete driven by a reference to *another* entity.
+  - Covered by name: **MongoDB/Mongoose** (`deleteMany({ userId })`, including
+    ES6 shorthand), **Firestore** (`collectionGroup` / recursive subcollection
+    delete, where the field name is an argument, not a key), **DynamoDB**
+    (`DeleteItem` / `BatchWriteItem` keyed by a parent), **CouchDB** (`_deleted:
+    true` in a `bulkDocs`), **Redis** (the key-pattern wipe — the prefix *is* the
+    parent), **Elasticsearch** (`deleteByQuery` on a parent field). ORM
+    declarations were already matched: `CascadeType.REMOVE`/`ALL`,
+    `orphanRemoval`, `DeleteBehavior.Cascade`, Prisma/Sequelize `onDelete:
+    Cascade`, Django `on_delete=models.CASCADE`, Rails `dependent: :destroy` /
+    `:delete_all`, SQLAlchemy `cascade = "…delete…"`.
+  - **Near-miss fixtures guard the false-positive side**, because a rule that
+    fires on ordinary deletes gets switched off and the coverage goes with it:
+    deleting a row by its own identity, `updateMany` by reference, a Redis `del`
+    of one known key, a Firestore query on a plain field, a CouchDB bulk insert,
+    an ES delete-by-query on a non-reference, a DynamoDB point read — all clean.
+  - A fire asks for a **declaration**, it does not claim the ownership is wrong;
+    `model.handWrittenCascade: false` switches it off and
+    `model.extraHandWrittenPatterns` adds a project's own dialect (an invalid
+    regex is dropped, never fatal).
+  - `test-model-gate.mjs` grew from 73 to **92 checks**, and the assertion that
+    recorded this as a *documented gap* ("a hand-rolled document-store cascade is
+    not caught — invariant tests carry it") is now inverted to assert it **is**
+    caught. The production shape that started this — `deleteMany({ question_id:
+    { $in: ids } })` over a child collection — is the fixture.
+
 ## [0.13.1] - 2026-10-16
 
 ### Fixed

package/lib/code-health/config.mjs

@@ -48,9 +48,14 @@ export const DEFAULT_CONFIG = {
     enabled: true,
     requireDeclaration: true, // cascade requires an asf-model: declaration
     deleteRebuild: true, // delete + reinsert of the same target
+    // A cascade written by hand in a store with no FK action to inspect —
+    // MongoDB, Firestore, DynamoDB, CouchDB, Redis, Elasticsearch. Without it
+    // the model gate reads as SQL-only, which is the blind spot 06j §5 names.
+    handWrittenCascade: true,
     declarationWindowLines: 8,
     rebuildWindowLines: 30,
     extraCascadePatterns: [],
+    extraHandWrittenPatterns: [],
   },
 
   ignore: [
@@ -171,12 +176,17 @@ export function normalizeConfig(raw) {
       enabled: bool(md.enabled, d.model.enabled),
       requireDeclaration: bool(md.requireDeclaration, d.model.requireDeclaration),
       deleteRebuild: bool(md.deleteRebuild, d.model.deleteRebuild),
+      handWrittenCascade: bool(md.handWrittenCascade, d.model.handWrittenCascade),
       declarationWindowLines: num(md.declarationWindowLines, d.model.declarationWindowLines),
       rebuildWindowLines: num(md.rebuildWindowLines, d.model.rebuildWindowLines),
       extraCascadePatterns:
         Array.isArray(md.extraCascadePatterns) && md.extraCascadePatterns.length > 0
           ? md.extraCascadePatterns.filter((x) => typeof x === "string" && x.length > 0)
           : [],
+      extraHandWrittenPatterns:
+        Array.isArray(md.extraHandWrittenPatterns) && md.extraHandWrittenPatterns.length > 0
+          ? md.extraHandWrittenPatterns.filter((x) => typeof x === "string" && x.length > 0)
+          : [],
     },
     ignore: Array.isArray(raw.ignore) && raw.ignore.every((x) => typeof x === "string") && raw.ignore.length > 0
       ? raw.ignore

package/lib/code-health/model.mjs

@@ -39,6 +39,72 @@ const CASCADE_DECL_RES = [
   { marker: 'cascade = "…delete…"', re: /\bcascade\s*=\s*["'][^"']*delete/i },
 ];
 
+/**
+ * Hand-written cascades in stores that enforce nothing (P27, 06j §5).
+ *
+ * A relational FK action and an ORM mapping attribute at least announce
+ * themselves. In a document, key-value, wide-column or search store there is no
+ * constraint to declare, so the cascade exists only as code someone wrote —
+ * which is exactly where an instance silently inherits its parent's lifecycle.
+ * These patterns look for a MULTI-delete driven by a reference to another
+ * entity: the shape of "when the parent goes, these go too", implemented by
+ * hand and nowhere written down.
+ *
+ * Illustrative, not exhaustive: a project adds its own dialect with
+ * `extraHandWrittenPatterns`. A fire here asks for a declaration; it does not
+ * claim the ownership is wrong — that judgement stays in review.
+ */
+const HANDWRITTEN_CASCADE_RES = [
+  { marker: "MongoDB/Mongoose deleteMany by reference", store: "document", re: /\.(?:deleteMany|remove|bulkDelete|destroyAll)\s*\(/ },
+  {
+    // Firestore spells a field name as an argument, not as a key:
+    // `where('postId', '==', id)`. The recursive subcollection delete is the
+    // classic way an instance inherits its parent's lifecycle here, and there
+    // is no constraint to enforce it — so the reference is a quoted field name.
+    marker: "Firestore collectionGroup / recursive delete",
+    store: "document",
+    re: /\.collectionGroup\s*\(|\bdeleteCollectionGroup\b|\bdeleteDoc\b|\.where\s*\(/i,
+    refRe: /["'`][\w.]*?(?:Id|_id)["'`]/,
+  },
+  { marker: "DynamoDB batch/point delete", store: "wide-column", re: /\b(?:DeleteItem|BatchWriteItem|deleteItem|batchWrite)\b/ },
+  {
+    // CouchDB has no cascade either: a set of documents is selected and marked
+    // `_deleted` in one bulk write. The selection IS the ownership decision, so
+    // this dialect carries its own reference test (null = the marker suffices).
+    marker: "CouchDB bulk delete",
+    store: "document",
+    re: /_deleted\s*[:=]\s*true|\bbulkDocs\s*\([^)]*_deleted/i,
+    refRe: null,
+  },
+  {
+    // A key-pattern wipe is the key-value store's cascade: everything under the
+    // parent's prefix goes with it. The `*` is the reference — there is no key
+    // to look for, so this dialect carries its own.
+    marker: "Redis key-pattern wipe",
+    store: "key-value",
+    re: /\.(?:keys|scan)\s*\([^)]*\*|\b(?:del|unlink)\s*\(/i,
+    refRe: /["'`][^"'`]*\*|\b\w*(?:Id|_id)\b/,
+  },
+  { marker: "Elasticsearch delete-by-query", store: "search", re: /(?:\.|_)delete_?by_?\s*query\s*\(|\bdeleteByQuery\b/i },
+];
+
+/**
+ * A key that names ANOTHER entity rather than the row's own identity. This is
+ * what turns "a delete happened" into "a cascade was implemented by hand":
+ * `deleteOne({ id })` is a row removing itself, `deleteMany({ userId })` is one
+ * entity deciding the fate of another.
+ */
+const PARENT_REF_RE =
+  /(?:^|[{,(\s])(?!id\b|_id\b|pk\b|key\b|rowId\b|selfId\b)[A-Za-z][A-Za-z0-9]*(?:Id|_id)\s*[:=]/;
+
+/**
+ * The same reference written as ES6 object shorthand — `deleteMany({ userId })`
+ * rather than `deleteMany({ userId: userId })`. Extremely common, and anchored
+ * to a brace pair so a bare `orderId` sitting in an enclosing parameter list
+ * does not turn an unrelated delete into a finding.
+ */
+const PARENT_REF_SHORTHAND_RE = /\{[^{}]*\b(?!id\b|_id\b|pk\b|key\b|rowId\b|selfId\b)[A-Za-z][A-Za-z0-9]*(?:Id|_id)\b[^{}]*\}/;
+
 /** Writes and deletions, matched on verb shape rather than store dialect. */
 const DELETE_VERBS = /^(deleteMany|deleteOne|deleteAll|destroyAll|bulkDelete|delete|remove|removeAll|destroy)$/i;
 const INSERT_VERBS = /^(insertMany|insertOne|createMany|bulkCreate|bulkWrite|insert|insertAll|save|upsert|create)$/i;
@@ -96,6 +162,33 @@ export function extraCascadePatterns(cfg) {
   return out;
 }
 
+/**
+ * Project-supplied dialect for the hand-written-cascade rule, same contract as
+ * extraCascadePatterns: a bad regex is skipped, never fatal. A project whose
+ * store is not in the illustrative set adds its own spelling rather than
+ * waiting for a release.
+ */
+export function extraPatterns(list, markerPrefix) {
+  const out = [];
+  for (const p of list || []) {
+    if (typeof p !== "string" || !p) continue;
+    try {
+      out.push({ marker: `${markerPrefix}: ${p}`, store: "project-declared", re: new RegExp(p, "i") });
+    } catch {
+      /* invalid regex — ignore rather than crash the gate */
+    }
+  }
+  return out;
+}
+
+/** The collection/table a statement acts on, when it names one. */
+export function targetOfStatement(stmt) {
+  const named = /\b(?:collection|from|table|model|entity|index)\s*\(\s*["']([\w.\-]+)["']/i.exec(stmt);
+  if (named) return named[1];
+  const receiver = /(?:^|[\s;}])([A-Za-z_$][\w$]*)\s*(?:\.\s*(?:deleteMany|deleteOne|delete|remove|bulkDelete|destroyAll|deleteByQuery|bulkDocs|keys|scan|del|unlink|deleteItem|batchWrite)\s*\()/i.exec(stmt);
+  return receiver ? receiver[1] : null;
+}
+
 /** Distance in lines to the nearest preceding asf-model tag, or null. */
 export function nearestTag(lines, idx, windowLines) {
   for (let d = 0; d <= windowLines; d++) {
@@ -214,6 +307,38 @@ export function scanModelSource(relPath, text, cfg = {}) {
     }
   }
 
+  // ── F3: a cascade implemented by hand in a store that enforces nothing ───
+  //
+  // The store-agnostic half of the gate. MongoDB, Firestore, DynamoDB, CouchDB,
+  // Redis and Elasticsearch have no FK action to inspect, so "the parent takes
+  // the children" exists only as a delete someone wrote. Catching it here is
+  // the difference between a model gate that reads as SQL-only and one that
+  // actually asks the question wherever the defect can happen.
+  if (cfg.handWrittenCascade !== false) {
+    const handWritten = [...HANDWRITTEN_CASCADE_RES, ...extraPatterns(cfg.extraHandWrittenPatterns, "custom hand-written cascade")];
+    for (let i = 0; i < lines.length; i++) {
+      const hit = handWritten.find((c) => c.re.test(lines[i]));
+      if (!hit) continue;
+      // The delete must be driven by a reference to another entity, else every
+      // ordinary `deleteOne({ id })` in a Mongo project would fire. `refRe: null`
+      // means the dialect's own marker already carries that meaning.
+      const stmt = enclosingStatement(lines, i);
+      const refRe = hit.refRe === undefined ? PARENT_REF_RE : hit.refRe;
+      if (refRe && !refRe.test(stmt) && !PARENT_REF_SHORTHAND_RE.test(stmt)) continue;
+      if (nearestTag(lines, i, tagWindow)) continue;
+      const child = childTableAt(lines, i) || targetOfStatement(stmt);
+      findings.push({
+        rule: "handwritten-cascade",
+        file: relPath,
+        line: i + 1,
+        table: child,
+        marker: hit.marker,
+        store: hit.store,
+        message: `${hit.marker}${child ? ` over ${child}` : ""} deletes by a reference to another entity — in a ${hit.store} store nothing enforces that, so this IS the cascade decision. Add \`asf-model: ${child || "<child>"} -> <parent> = composition|instance|ledger, owner: <who>\` within ${tagWindow} lines above, or \`asf-model-accept: <reason>\` (06j §2, §5).`,
+      });
+    }
+  }
+
   return findings.sort((a, b) => a.line - b.line || a.rule.localeCompare(b.rule));
 }
 
@@ -268,4 +393,4 @@ export async function scanModel(root, { files, readFile, config } = {}) {
   return { findings, scanned, errors };
 }
 
-export const MODEL_RULES = ["undeclared-cascade", "delete-then-reinsert"];
+export const MODEL_RULES = ["undeclared-cascade", "delete-then-reinsert", "handwritten-cascade"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-aia-asf",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "description": "Ai Applied Agentic Software Factory — codifies the full software development flow: intake, research, spec capture, adversarial analysis, planning with approval gates, test-first implementation, and release. Requires pi-vigilant, pi-smart-web-search, pi-smart-fetch, and pi-aia-browser.",
   "keywords": [
     "pi-package",

package/skills/aia-asf/references/06j-data-model.md

@@ -179,16 +179,38 @@ requirement: "is this ownership correct?" is judgment and stays in review, while
 "does this file declare a cascade with no `asf-model:` tag?" is measurable.
 
 **It is a tripwire, not an authority — and it is store-agnostic by design.** The
-defect is not SQL-shaped: an instance inheriting its parent's lifecycle happens
+defect is not SQL-shaped. An instance inheriting its parent's lifecycle happens
 in a relational FK action, in an ORM mapping attribute, in a document store's
 delete dependency, in a key-value prefix wipe, or in a loop someone wrote to
-delete children by hand. The scan recognises a small illustrative set of those
-spellings and a project adds its own dialect with `model.extraCascadePatterns`
-rather than waiting for a release. **Where the store has no constraint to
-inspect, the scan has nothing to attach to and the invariant tests below are the
-only hard gate** — say which of the two you relied on, and if the scan reported
-`scanned: 0`, say that too. A clean scan means the tripwire caught nothing, not
-that the model is sound.
+delete children by hand. Three rules run:
+`undeclared-cascade` (a cascade declaration with no ownership declaration),
+`delete-then-reinsert` (rebuild-by-delete over one table or collection), and
+`handwritten-cascade` — the shape a cascade takes in a store that has **no
+constraint to declare it in**, where the decision exists only as code someone
+wrote: a multi-delete driven by a reference to *another* entity.
+
+The distinction that makes `handwritten-cascade` decidable rather than
+judgemental is the **reference**. `deleteOne({ _id: id })` is a row removing
+itself; `deleteMany({ userId })` is one entity deciding the fate of another. The
+first does not fire — a rule that fires on ordinary deletes gets switched off and
+the coverage goes with it, which is why the near-miss fixtures matter more than
+the fire fixtures. A fire asks for a **declaration**; it does not claim the
+ownership is wrong, and that judgement stays in review.
+
+**The pattern set is illustrative and the standard does not enumerate products.**
+The categories above are the standard; the dialects the scanner happens to
+recognise are an implementation detail in `lib/code-health/model.mjs`, reported
+per finding so you can see what it looked at. A project whose store is not in
+that set adds its own spelling with `model.extraCascadePatterns` /
+`model.extraHandWrittenPatterns` rather than waiting for a release — and a
+recognised dialect is not a coverage promise. If your persistence layer speaks a
+shape the scanner does not know, that is a `scanned: 0` you must say out loud,
+not a clean bill of health.
+
+**Where the store has no constraint to inspect, the scan has nothing to attach
+to and the invariant tests below are the only hard gate** — say which of the two
+you relied on, and if the scan reported `scanned: 0`, say that too. A clean scan
+means the tripwire caught nothing, not that the model is sound.
 
 **Invariant and non-effect tests** — [06g-test-design.md](06g-test-design.md) §3:
 survival tests, non-effect assertions, zero-row invariant queries, two-user