@githonllc/avouch 0.1.3 → 0.1.4

package/README.md

@@ -130,7 +130,7 @@ Inside a Claude Code session, the same two steps are `/plugin marketplace add gi
 
 The plugin has two skills:
 - `cli` (`/avouch:cli`): checks an ontology and runs `avouch query`.
-- `scan` (`/avouch:scan [project-dir]`): drafts or updates a project's ontology from its design documents. The result is a candidate. `avouch check` must exit 0, and each source gap is listed with a proposed fix to the document.
+- `scan` (`/avouch:scan [project-dir]`): drafts or updates a project's ontology from its design documents. The result is a candidate. `avouch check` must exit 0, and each source gap is listed with a proposed fix to the document. When most objects have no documented field list, it also writes `avouch/doc-patch.md`: field lists, foreign keys and store names derived from the code, for a human to review and merge into the documents. It never drafts states, permissions or rules from code.
 
 Before 0.1.3 the two skills were named `avouch-cli` and `aquery-scan`.
 

package/SPEC.md

@@ -49,7 +49,7 @@ The definitions quoted in the "Palantir analog" column are short quotations from
 | `actionTypes.<A>.parameters` | foundation | action parameter: "Parameters are the inputs of an action type." | name → `{cite, type?, optional?, values?}`; read by a condition as `{param}` or, in an expression, `{ref}`; `type` is needed when an expression reads it; `optional: true` lets the caller omit it; `values` (only with `type: enum`) is the value domain of the parameter; R1, R2 |
 | `conditions` | foundation + constraint | submission criteria: "the conditions that determine whether an action can be submitted"; Palantir submission criteria ≈ the rows whose disposition class is `rejected` | named Boolean claims `{id, expr \| unspecified, reads?, reads_unspecified?, cites[{cite}], scenarios?}`: `expr` is the claim as an expression (section 9); `unspecified` says it is not written as one, and `reads` may then list what it reads (properties, parameters `{param, values?}`, the caller `{actor: id}` / `{actor: keys}`); R1, R4, R12 |
 | `decision` | extension | none | decision table `{hitPolicy: first, order?: {cite}, rows: [{when: {passes \| fails: <condition>}, result, cites, next?}], otherwise?: {result, cites, next?}}`; `next` is `{actions}`, `{external, cite}` or `{unspecified}`; R1, R12 |
-| `edits` / `creates` | foundation | action rules: modify / create object | |
+| `edits` / `creates` / `deletes` | foundation | action rules: modify / create / delete object | `deletes` is a hard delete of datasource rows; a soft delete is an `edits` |
 | `link_effects` | foundation + constraint | action rules: create / delete link | every incident link needs an entry, including `none` / `unspecified` (R6 sweep) |
 | `emits` | extension | none (Palantir side effects are notifications / webhooks after submission) | events written in the same operation; R7, R8 |
 | `permission` | extension | roles / submission criteria on the current user are approximate. Forms: `unknown`, `{keys, cite, …}`, `{none, cite}` (optionally with `principals`), `{any_of: [keys-form, …]}` (OR of keys-forms, at least 2) | R1, R10 |
@@ -110,11 +110,11 @@ The adapter may read the ontology instance (for example to list action ids in a
 | R4 | conditions read only canonical and policy properties, for an expression also through the derived properties it reaches (parameter and actor reads are request inputs, not state, and are not classified; a derived property without `expr` is not expanded; a hand-written `reads` entry that names a derived property is expanded through its `reads`, or, when it has an `expr`, through the properties that expression reads, as for an expression condition); a non-canonical property passes when every read compares it by `eq` / `neq` with a literal in its `canonical_values`; canonical values and the values of a parameter read appear in their quote (`parameter_value_unsupported`); each literal of an expression appears in one of its condition's quotes, or in the derived property's quote (`literal_unsupported`, key `<ID>:<condition id>:<value>` or `derivedProperties.<id>:<value>`) | none | the property reads of conditions are canonical or policy facts; literals are not invented | that `reads` is complete; that an expression's logic matches its cite |
 | R5 | object membership, cross-context declaration (`via` or `unspecified`), `create_rule`, entity coverage | `contextMembers`, `config.crossContextMechanisms` | object ownership matches the source | the content of the mechanism |
 | R6 | link sweep, link catalog complete (with `scope`, the `<by>` field of a tenant type counts as declared and must not be in `non_link_fields`: `non_link_field_stray`), `none_but_written` | `fieldList`, `config.linkFieldPattern`, `evidence` | link effects are declared completely | that an effect text is right |
-| R7 | observed writes are declared; events are in `emits`; changed columns are declared (`column_undeclared`, key `<ID>:<Object>.<prop>`); declared effects are witnessed (`effect_unwitnessed`); with `config.evidenceRequired: true` (default `false`) an action without `evidence` fails `evidence_missing` (key `<ID>`) | `evidence`, `config.evidenceRequired` | every store changed by a committed invocation is in the touched objects' `datasource`, a pure link table with an `effect`, or `infrastructureStores`; every observed event is in `emits`; every column changed on an existing row of a touched object's `datasource` is, for each touched object of that store, a property of a resolvable `edits` entry of that same object (objects may share a store; a column that one object declares is still reported for each other touched object of the store that does not declare it); every resolvable `edits` entry (resolved as R1 resolves it; an unresolvable entry is R1 only) was changed on an existing row (key `<ID>:<Object>.<prop>`), every `creates` object had a row inserted (key `<ID>:creates:<Object>`) and every pure link table with an `effect` had a row inserted or deleted (key `<ID>:link:<link id>`) by at least one committed invocation | actions without evidence (unless `evidenceRequired`); that a not yet witnessed effect is unreachable; atomicity, which refers to the committed effect (one invocation may have several attempts) and which the project profile or evidence adapter must enforce |
+| R7 | observed writes are declared; events are in `emits`; changed columns are declared (`column_undeclared`, key `<ID>:<Object>.<prop>`); declared effects are witnessed (`effect_unwitnessed`); with `config.evidenceRequired: true` (default `false`) an action without `evidence` fails `evidence_missing` (key `<ID>`) | `evidence`, `config.evidenceRequired` | every store changed by a committed invocation is in the touched objects' `datasource`, a pure link table with an `effect`, or `infrastructureStores`; every observed event is in `emits`; every column changed on an existing row of a touched object's `datasource` is, for each touched object of that store, a property of a resolvable `edits` entry of that same object (objects may share a store; a column that one object declares is still reported for each other touched object of the store that does not declare it); every resolvable `edits` entry (resolved as R1 resolves it; an unresolvable entry is R1 only) was changed on an existing row (key `<ID>:<Object>.<prop>`), every `creates` object had a row inserted (key `<ID>:creates:<Object>`), every `deletes` object had a row deleted (key `<ID>:deletes:<Object>`) and every pure link table with an `effect` had a row inserted or deleted (key `<ID>:link:<link id>`) by at least one committed invocation | actions without evidence (unless `evidenceRequired`); that a not yet witnessed effect is unreachable; atomicity, which refers to the committed effect (one invocation may have several attempts) and which the project profile or evidence adapter must enforce |
 | R8 | emitted events are in the catalog | `eventCatalog` | | |
 | R9 | scenario cross references | `scenarios` | every action is cited; with `config.scenarioCoverage: "enforced"` (default `"printed"`, coverage only printed) every condition without `scenarios` fails `criterion_uncovered` (key `<ID>:<condition id>`) and every non-`none`, non-`unspecified` link effect without `scenarios` fails `effect_uncovered` (key `<ID>:<link id>`); `unspecified` effects are not reported again, R6 reports them | with `printed`, that scenarios cover every condition; that a listed scenario supports the claim |
 | R10 | permission key sets equal the source rows (for `any_of`: the union over alternatives of keys ∪ conditional_keys; each alternative's cite must also name its own keys); cites name the required source | `permissions`, `config.requiredSource.R10` | keys match the source | |
-| R11 | an action that edits an input lists the materialized property | none | declaration is complete | same-operation atomicity of the committed effect (one invocation may have several attempts), which the evidence adapter guarantees |
+| R11 | an action that edits an input, creates an input's object, or deletes an input's object (unless it also deletes the materialized property's own object, whose row is gone) lists the materialized property. An action that deletes the property's own object and also edits or creates an input is still reported, because the edited inputs may belong to other rows; waive it with a reason when they cannot. | none | declaration is complete | same-operation atomicity of the committed effect (one invocation may have several attempts), which the evidence adapter guarantees |
 | R12 | decision tables, all waivable: an action with conditions has a `decision` (`decision_table_missing`, key `<ID>`); a table has `otherwise` (`otherwise_missing`); a row does not use a condition without expression, or one that reaches a derived property without expression (`condition_unspecified`, key `<ID>:<condition id>`) (implementation decision: like the R4 and literal checks, the derived-property part is computed only for conditions whose expression passes the R1 type check); rows with different results have `order` (`row_order_uncited`); for rows `i < j` with different results whose position cites are in one section, the position of `i` comes first (`row_order_mismatch`, key `<ID>:rows.<i>:rows.<j>`, once per pair; implementation decision, since facts carry no order across sections: a row's position cite is in the section of the first listed cite whose quote names its result, and its position is the earliest such quote in that section). A row whose position-cite section is `missing` or `ambiguous` has no position and is not compared. Rows whose position cites are in different sections are not compared, even if they also cite a shared section; ordering across sections relies on `decision.order` and scenarios with overlapping inputs; each row names its result in a cite quote (`result_unsupported`, key `<ID>:rows.<i>` or `<ID>:otherwise`); `next: {unspecified}` is reported (`next_unspecified`); a row `passes(c)` where c may be UNKNOWN, no earlier row is `fails(c)`, and a later row up to the first later `fails(c)` row (inclusive), or `otherwise` when there is no such row, has class `applied` or `pending` (`unsafe_fallthrough`, key `<ID>:rows.<i>`); the body of an `exists` / `none` / `all` may be UNKNOWN (`quantifier_absorbs_unknown`, key `<ID>:<condition id>:<path>` or `derivedProperties.<id>:<path>`, path as in type errors, for example `$.and[1].none`); both see section 9, Static UNKNOWN analysis | `section`, `fieldList` | every row has a source for its result and, within one section, for its place | that rows do not overlap; that the order cite covers the whole table |
 
 ## 6. Rule switches
@@ -146,7 +146,7 @@ The table lists only the optional facts. Every rule may also read the required f
 
 ## 8. Versions
 
-The version is in two places: `v1` in the schema `$id`, and `formatVersion: 1` in the ontology file (R1 fails on any other value). A change that breaks existing ontologies raises both. A change that rejects only files without meaning (for example an empty name) is not a break. Adding the `permission.any_of` form is additive: existing files stay valid, so `formatVersion` stays 1. Adding `parameters` and the parameter and actor reads of the submission criteria (since renamed `conditions`) is additive: existing files stay valid, so `formatVersion` stays 1. Adding `values` on enum parameters is additive; `formatVersion` stays 1.
+The version is in two places: `v1` in the schema `$id`, and `formatVersion: 1` in the ontology file (R1 fails on any other value). A change that breaks existing ontologies raises both. A change that rejects only files without meaning (for example an empty name) is not a break. Adding the `permission.any_of` form is additive: existing files stay valid, so `formatVersion` stays 1. Adding `parameters` and the parameter and actor reads of the submission criteria (since renamed `conditions`) is additive: existing files stay valid, so `formatVersion` stays 1. Adding `values` on enum parameters is additive; `formatVersion` stays 1. Adding `deletes` is additive; `formatVersion` stays 1.
 During 0.x the v1 draft changes in place (`formatVersion` 1, `$id` v1); the rule above applies from the 1.0 semantic freeze.
 
 ## 9. Decision semantics

package/dist/src/checker.js

@@ -261,6 +261,8 @@ export function check(ontology, facts) {
                 v("R1", p, `${f} must be a list`);
         if (c.creates !== undefined && !Array.isArray(c.creates))
             v("R1", p, "creates must be a list");
+        if (c.deletes !== undefined && !Array.isArray(c.deletes))
+            v("R1", p, "deletes must be a list");
         if (!isObj(c.link_effects))
             v("R1", p, "link_effects missing (use {})");
         if (c.crossContext !== undefined) {
@@ -322,6 +324,9 @@ export function check(ontology, facts) {
         for (const o of arr(c.creates))
             if (!objType(o) && !outOfScope.has(o))
                 v("R1", p, `creates ${o}: unknown object`);
+        for (const o of arr(c.deletes))
+            if (!objType(o) && !outOfScope.has(o))
+                v("R1", p, `deletes ${o}: unknown object`);
         for (const e of Object.keys(isObj(c.edit_cites) ? c.edit_cites : {}))
             if (!arr(c.edits).includes(e) || !isObj(c.edit_cites[e]?.cite))
                 v("R1", `${p}.edit_cites.${e}`, "must name an edit and carry a cite");
@@ -633,7 +638,7 @@ export function check(ontology, facts) {
             if (!entities.has(x))
                 v("R5", `entity:${x}`, `outOfScopeObjectTypes.${x} is not a source entity`, "out_of_scope_unknown");
     }
-    const touched = (c) => new Set([...arr(c.edits).map((e) => e.split(".")[0]), ...arr(c.creates)].filter(objType));
+    const touched = (c) => new Set([...arr(c.edits).map((e) => e.split(".")[0]), ...arr(c.creates), ...arr(c.deletes)].filter(objType));
     for (const [cid, c] of Object.entries(commands)) {
         if (!isObj(c))
             continue;
@@ -713,7 +718,7 @@ export function check(ontology, facts) {
     // columns changed on existing rows (per store; checked per object), and the events written
     const observe = (id) => {
         const committed = part(id).committed;
-        const rowStores = new Set(), insertedStores = new Set(), insDelStores = new Set(), events = new Set();
+        const rowStores = new Set(), insertedStores = new Set(), insDelStores = new Set(), deletedStores = new Set(), events = new Set();
         const changedCols = new Map();
         for (const i of committed) {
             for (const e of i.delta.events)
@@ -723,6 +728,8 @@ export function check(ontology, facts) {
                     rowStores.add(tb);
                 if (d.inserted.length)
                     insertedStores.add(tb);
+                if (d.deleted.length)
+                    deletedStores.add(tb);
                 if (d.inserted.length || d.deleted.length)
                     insDelStores.add(tb);
                 for (const u of d.updated)
@@ -730,7 +737,7 @@ export function check(ontology, facts) {
                         changedCols.set(tb, (changedCols.get(tb) ?? new Set()).add(col));
             }
         }
-        return { committed, rowStores, insertedStores, insDelStores, changedCols, events };
+        return { committed, rowStores, insertedStores, insDelStores, deletedStores, changedCols, events };
     };
     for (const [cid, c] of Object.entries(commands)) {
         if (!isObj(c))
@@ -783,14 +790,14 @@ export function check(ontology, facts) {
                 v("R7", cid, "the profile requires evidence, but the action declares none", "evidence_missing");
     if (facts.evidence !== undefined) {
         // a pure link table (not any object's table) may be written when the action declares an `effect` on that link;
-        // an object's table still needs the object in edits / creates
+        // an object's table still needs the object in edits / creates / deletes
         const objTables = new Set(Object.values(objects).map((o) => o?.datasource));
         for (const [cid, c] of Object.entries(commands)) {
             if (!isObj(c) || c.evidence === undefined)
                 continue;
             claimed.add(c.evidence);
             const { rejected } = part(c.evidence);
-            const { committed, rowStores, insertedStores, insDelStores, changedCols, events } = observe(c.evidence);
+            const { committed, rowStores, insertedStores, insDelStores, deletedStores, changedCols, events } = observe(c.evidence);
             const attempts = [...committed, ...rejected].reduce((n, i) => n + i.rolledBackAttempts, 0); // malformed records add nothing
             info.push(`R7 ${cid} (${c.evidence}, ${committed.length} committed, ${rejected.length} rejected invocations, ${attempts} rolled-back attempts): changed {${[...rowStores].sort()}} events {${[...events].sort()}}`);
             if (!committed.length) {
@@ -804,7 +811,7 @@ export function check(ontology, facts) {
             const allowed = new Set([...declared, ...linkTables, ...infra]);
             for (const tb of rowStores)
                 if (!allowed.has(tb))
-                    v("R7", `${cid}:${tb}`, `evidence (${c.evidence}) changed store ${tb}, not declared by edits/creates`, "table_undeclared");
+                    v("R7", `${cid}:${tb}`, `evidence (${c.evidence}) changed store ${tb}, not declared by edits/creates/deletes`, "table_undeclared");
             for (const e of events)
                 if (!arr(c.emits).includes(e))
                     v("R7", `${cid}:event:${e}`, `evidence (${c.evidence}) wrote event ${e}, not in emits`, "event_undeclared");
@@ -831,6 +838,9 @@ export function check(ontology, facts) {
             for (const o of arr(c.creates))
                 if (objType(o) && !insertedStores.has(objects[o].datasource))
                     unwitnessed(`creates:${o}`, `inserted a row into ${objects[o].datasource}`);
+            for (const o of arr(c.deletes))
+                if (objType(o) && !deletedStores.has(objects[o].datasource))
+                    unwitnessed(`deletes:${o}`, `deleted a row of ${objects[o].datasource}`);
             for (const l of links.filter(pureLink))
                 if (!insDelStores.has(l.table))
                     unwitnessed(`link:${l.id}`, `inserted or deleted a row of the link store ${l.table}`);
@@ -967,7 +977,9 @@ export function check(ontology, facts) {
             for (const [cid, c] of Object.entries(commands)) {
                 if (!isObj(c))
                     continue;
-                const hit = reads.filter((r) => arr(c.edits).includes(r) || arr(c.creates).includes(r.split(".")[0]));
+                // deleting an input object writes it, unless the target's own object is deleted too (the target row is gone)
+                const hit = reads.filter((r) => arr(c.edits).includes(r) || arr(c.creates).includes(r.split(".")[0])
+                    || (arr(c.deletes).includes(r.split(".")[0]) && !arr(c.deletes).includes(name)));
                 if (hit.length && !arr(c.edits).includes(target))
                     v("R11", `${cid}:${target}`, `${cid} writes ${hit.join(", ")} (inputs of ${target}) but does not list ${target} in edits`, "materialization_missing");
             }

package/dist/src/query.d.ts

@@ -162,6 +162,7 @@ export type QueryAction = {
         cite: QueryCite | null;
     }[];
     creates: string[];
+    deletes: string[];
     emits: string[];
     linkEffects: {
         link: string;
@@ -232,6 +233,7 @@ export type QueryObject = {
         action: string;
         edits: string[];
         creates: boolean;
+        deletes: boolean;
     }[];
     readers: {
         action: string;
@@ -261,6 +263,7 @@ export type QueryWrites = {
         path: string[];
     }[];
     creators: string[];
+    deleters: string[];
 };
 export type QueryReads = {
     target: string;

package/dist/src/query.js

@@ -344,6 +344,7 @@ export function queryAction(ont, id) {
         decision: isObj(a.decision) ? { order: citeOf(map(a.decision.order).cite), rows: decisionRows(an, id, a) } : null,
         edits: strs(a.edits).map((prop) => ({ prop, cite: citeOf(map(own(editCites, prop)).cite) })),
         creates: strs(a.creates),
+        deletes: strs(a.deletes),
         emits: strs(a.emits),
         linkEffects: Object.entries(map(a.link_effects)).flatMap(([link, le]) => {
             const e = map(le);
@@ -396,8 +397,9 @@ export function queryObject(ont, id) {
     for (const [aid, a] of sortedActions(ont)) {
         const edits = strs(a.edits).filter((e) => e.startsWith(prefix));
         const creates = strs(a.creates).includes(id);
-        if (edits.length || creates)
-            writers.push({ action: aid, edits, creates });
+        const deletes = strs(a.deletes).includes(id);
+        if (edits.length || creates || deletes)
+            writers.push({ action: aid, edits, creates, deletes });
     }
     if (o === undefined)
         return { id, context: null, datasource: null, doc: null, outOfScope, scope: null, properties: [], derived: [], stateMachine: null, links: [], writers, readers: [], unanalyzed: [] };
@@ -494,7 +496,8 @@ export function queryWrites(ont, t) {
     const acts = sortedActions(ont);
     const writersOf = (prop, path) => acts.filter(([, a]) => strs(a.edits).includes(prop)).map(([aid, a]) => ({ action: aid, cite: citeOf(map(own(map(a.edit_cites), prop)).cite), path }));
     if (tg.kind === "property")
-        return { target: t, kind: "property", unanalyzed: [], writers: writersOf(t, []), creators: acts.filter(([, a]) => strs(a.creates).includes(tg.obj)).map(([aid]) => aid) };
+        return { target: t, kind: "property", unanalyzed: [], writers: writersOf(t, []), creators: acts.filter(([, a]) => strs(a.creates).includes(tg.obj)).map(([aid]) => aid),
+            deleters: acts.filter(([, a]) => strs(a.deletes).includes(tg.obj)).map(([aid]) => aid) };
     // Breadth first from the derived target: each input once, by its shortest path.
     const an = new Analysis(ont);
     const writers = [];
@@ -518,7 +521,7 @@ export function queryWrites(ont, t) {
         frontier = next;
     }
     writers.sort((a, b) => a.path.length - b.path.length || sortStr(a.path.join(), b.path.join()) || sortStr(a.action, b.action));
-    return { target: t, kind: "derived", unanalyzed: derivedErrors(an, seenDerived), writers, creators: [] };
+    return { target: t, kind: "derived", unanalyzed: derivedErrors(an, seenDerived), writers, creators: [], deleters: [] };
 }
 export function queryReads(ont, t) {
     const tg = target(ont, t);

package/ontology.schema.json

@@ -689,6 +689,13 @@
           },
           "description": "Objects the action creates (optional). Foundation (closest analog: the create-object rules of a Palantir action type). R1: each must be a key of `objectTypes` or of `outOfScopeObjectTypes`. Declared objects here are touched (R5, R6, R7) and count as writing every property of that object for R11. R5: creating the `from` object of a link with `create_rule` triggers that rule."
         },
+        "deletes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Objects whose rows the action removes (optional). Foundation (closest analog: the delete-object rules of a Palantir action type). R1: each must be a key of `objectTypes` or of `outOfScopeObjectTypes`. A soft delete is an `edits` of the marker property. Declared objects here are touched (R5, R6, R7). R7: for an action with `evidence`, each declared object here must have a row of its datasource deleted by at least one committed invocation (else `effect_unwitnessed`, key `<ID>:deletes:<Object>`); an upsert declares `creates`, not `deletes`. R11: deleting an input of a `materializedFrom` property counts as writing it, unless the object of that property is also listed here."
+        },
         "edit_cites": {
           "type": "object",
           "propertyNames": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githonllc/avouch",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",