@punica/editor 1.24.0 → 1.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punica/editor",
-  "version": "1.24.0",
+  "version": "1.25.0",
   "description": "Punica Editor",
   "private": false,
   "type": "module",
@@ -26,6 +26,7 @@
     "check:permissions": "node scripts/check-permissions.mjs",
     "check:empty-states": "node scripts/check-empty-states.mjs",
     "check:capability-handlers": "node scripts/check-capability-handlers.mjs",
+    "report:capability-actions": "node scripts/report-capability-actions.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:ui": "vitest --ui",

package/types/punica.module.capability.d.ts

@@ -176,6 +176,45 @@ declare module 'punica' {
     [key: string]: unknown;
   }
 
+  /**
+   * What a capability DOES, from a closed vocabulary — the axis a policy
+   * rule can address when the id space cannot.
+   *
+   * The substrate ships two ids for the same action more than once:
+   * `fs.readFile` and `workspace.readFile` read the same file, so a rule
+   * denying `fs.*` says nothing about the second one. Measured
+   * 2026-08-30 with a model in the loop and again without one: same
+   * workspace, same path, identical `argsBinding`, one denied and one
+   * allowed. The rule engine was right; the vocabulary the rules address
+   * was too narrow. A rule may now select `action: [file.read]` and
+   * cover both.
+   *
+   * Closed on purpose, unlike the open `sideEffects` list beside it. Two
+   * reasons: an open vocabulary cannot be relied on by a rule author who
+   * has to guess the spelling, and `extension-policy-export` expands an
+   * action rule back into ids before it leaves the machine — an
+   * expansion is only sound while both sides agree on the term.
+   *
+   * Declaring is voluntary and its absence changes nothing: a capability
+   * with no `action` is matched by id exactly as it was before this
+   * existed. There is no implicit deny anywhere in this file.
+   */
+  export type CapabilityAction =
+    | 'file.read'
+    | 'file.write'
+    | 'file.list'
+    | 'file.stat'
+    | 'secret.read'
+    | 'secret.write'
+    | 'process.exec'
+    | 'net.request'
+    | 'model.invoke'
+    | 'memory.read'
+    | 'memory.write'
+    | 'vcs.read'
+    | 'vcs.write'
+    | 'flow.run';
+
   /**
    * Unified Capability Definition - Base interface for all capability types.
    *
@@ -267,6 +306,21 @@ declare module 'punica' {
      */
     sideEffects?: string[];
 
+    /**
+     * What this capability does, from the closed `CapabilityAction`
+     * vocabulary — the axis `.punica/policy.yaml` rules can address
+     * instead of an id.
+     *
+     * A list rather than one value because a capability can genuinely do
+     * two things: `fs.copy` reads a file and writes another, and
+     * declaring only the write would hide half of what a rule needs to
+     * see. Declare what the call PERFORMS, not what its name suggests —
+     * `search.query` returns matching lines, so it reads files.
+     *
+     * Contract: `docs/capability-actions.md`.
+     */
+    action?: CapabilityAction[];
+
     /**
      * Required context for this capability to execute.
      * Examples: ['workspace', 'active-file', 'selection']

package/types/punica.module.kernel.ai.d.ts

@@ -132,6 +132,20 @@ declare module 'punica' {
         usage?: runtime.LlmUsage;
         /** Wall-clock duration of this turn's LLM call, in milliseconds. */
         latencyMs?: number;
+        /**
+         * Why the turn ended without a model response. Absent on a turn
+         * that produced one, which is every turn in a run that finished
+         * normally.
+         *
+         * The field exists because the turn's span has to be published
+         * either way: the model call and any compaction before it are
+         * already children of it, and a parent nobody emits leaves the
+         * reader a tree of ghosts. So a failed turn is a node that says
+         * what happened to it rather than a node that is missing.
+         */
+        outcome?: 'error' | 'cancelled';
+        /** The failure text, when `outcome` is `'error'`. */
+        error?: string;
       }
 
       /**

package/types/punica.module.kernel.llm.d.ts

@@ -138,6 +138,18 @@ declare module 'punica' {
           modelId?: string;
           provider?: string;
           cacheHit?: boolean;
+          /**
+           * Content digest of the prompt that produced this answer —
+           * see `runtime.LlmCallMeta.promptVersion`.
+           *
+           * It rides on the OUTPUT rather than only on the `llm.call`
+           * event because that event is published `kind: 'info'` and
+           * dies with the in-memory ring, while a capability's output
+           * reaches the durable audit record. An evidence package
+           * answering "which prompt produced this run" has to read it
+           * from disk.
+           */
+          promptVersion?: string;
         };
       }
 

package/types/punica.module.kernel.policy.d.ts

@@ -16,6 +16,20 @@ declare module 'punica' {
        * Identifier within the kind (e.g. capabilityId, providerId).
        */
       id: string;
+      /**
+       * What the guarded action performs, from the closed
+       * `CapabilityAction` vocabulary — read off the capability's own
+       * declaration by the gate, never invented here.
+       *
+       * This is what lets a rule cover a synonym: `fs.readFile` and
+       * `workspace.readFile` are two ids for one action, and before
+       * this field a rule about the first was silent about the second.
+       *
+       * Absent for a request with no capability behind it (`llm.remote`,
+       * a flow step) and for a capability that declares nothing — both
+       * key exactly as they did before actions existed.
+       */
+      action?: CapabilityAction[];
       risk: PolicyRisk;
       approval: PolicyApproval;
       /**
@@ -376,6 +390,27 @@ declare module 'punica' {
       kind: string;
       /** Exact id, or a trailing-`*` prefix glob. Absent matches every id of the kind. */
       id?: string;
+      /**
+       * Which actions this rule is about, from the closed
+       * `CapabilityAction` vocabulary — the selector that covers a
+       * synonym the id space hides. A rule denying `fs.*` said nothing
+       * about `workspace.readFile`, which reads the same file
+       * (measured 2026-08-30); `action: ['file.read']` covers both.
+       *
+       * ANDed with `id` when both are present. Absent matches on id
+       * alone, which is every rule written before this existed.
+       *
+       * The quantifier depends on the effect, for the same reason a
+       * wildcard condition's does. For `deny`/`require`, ANY declared
+       * action named here is enough. For `allow`, EVERY action the
+       * capability declares must be named — otherwise an allow written
+       * for `file.write` would also release `fs.copy`, which reads.
+       *
+       * A capability that declares no action is matched by id only; an
+       * action rule never reaches it. Contract:
+       * `docs/capability-actions.md`.
+       */
+      action?: CapabilityAction[];
       effect: PolicyRuleEffect;
       /** ANDed. Absent or empty matches every argument tuple. */
       when?: PolicyCondition[];
@@ -395,6 +430,12 @@ declare module 'punica' {
       reason?: string;
       /** Digest of the template's rules — which policy text was in force. */
       digest?: string;
+      /**
+       * Which selector matched: the capability's id, or an action it
+       * declares. A reader of the audit record can otherwise not tell
+       * why a rule naming no id applied to this call.
+       */
+      matchedBy?: 'id' | 'action';
     }
 
     /** A rule that matched, plus the rule itself for the caller to read. */

package/types/punica.module.runtime.llm.d.ts

@@ -252,6 +252,29 @@ declare module 'punica' {
        * "gpt-4o", "llama3:70b-q4_K_M").
        */
       model: string;
+      /**
+       * Which prompt was used, as a content digest of the resolved
+       * instruction class — its id, system prompt, output schema and
+       * response format, SHA-256 truncated to 128 bits of hex.
+       *
+       * A digest rather than a version number because there is no
+       * version to read: no `.ic.yaml` carries one and
+       * `InstructionClass` has no such field, so any counter here would
+       * be a number nobody maintains. This is the field LLMOps 2.1 left
+       * open, and the decision it was waiting for.
+       *
+       * Deliberately NOT covered: `temperature`, `maxTokens`,
+       * `expertModelId` and the provider chain. Those are how the call
+       * was made rather than what was asked, and the model that
+       * answered is already on `model` beside this. Two calls sharing a
+       * `promptVersion` were asked the same thing — not necessarily
+       * under the same conditions.
+       *
+       * Absent on a path that resolves no instruction class
+       * (`llm.chat`, `llm.chatStream`), which is every call the model
+       * makes directly rather than through a named prompt.
+       */
+      promptVersion?: string;
       promptTokens: number;
       completionTokens: number;
       /**