@punica/editor 1.20.0 → 1.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punica/editor",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "Punica Editor",
   "private": false,
   "type": "module",

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

@@ -150,9 +150,20 @@ declare module 'punica' {
       getRecent(limit?: number): KernelEvent[];
 
       /**
-       * Filter events by various criteria.
-       * By default, only searches in-memory audit buffer.
-       * Set includePersisted=true to also search disk-persisted events (may be slower).
+       * Filter events by various criteria. **In-memory audit buffer only** —
+       * the bounded ring, not the durable store.
+       *
+       * `includePersisted` is accepted and does nothing. Reading the store is
+       * async and this signature is not, so the flag was left as a placeholder
+       * and the doc claimed it worked; a consumer that trusted it got the ring
+       * and no indication of what it missed. Corrected 2026-08-28 after an
+       * evidence package would have reported a run as shorter than it was.
+       *
+       * To read the store, call `loadPersistedEvents` and merge — the two sets
+       * overlap and both are needed, because persistence batches at ten records
+       * or five seconds and a just-finished run is not on disk yet.
+       *
+       * @deprecated includePersisted — pass nothing; use `loadPersistedEvents`.
        */
       filterEvents(options?: {
         correlationId?: string;

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

@@ -89,6 +89,61 @@ declare module 'punica' {
       signal?: AbortSignal;
     }
 
+    /**
+     * The closed vocabulary of lineage subject kinds.
+     *
+     * A capability schema declares a field a subject with the
+     * non-standard `subject: '<kind>'` keyword, and the gateway copies
+     * what it finds onto the audit record. That record is the only
+     * source an evidence package has for "which data did this run
+     * touch?", which is why the kinds are closed: a reader comparing
+     * two packages cannot interpret a word an author invented.
+     *
+     * `dataset` is a named body of data, `file` a workspace path whose
+     * contents a call read or wrote, `model` a model that produced
+     * something, `prompt` the configured behaviour it ran with,
+     * `collection` a vector index a retrieval read from, and `artifact`
+     * something the run produced.
+     */
+    export type SubjectKind =
+      | 'dataset'
+      | 'file'
+      | 'model'
+      | 'prompt'
+      | 'collection'
+      | 'artifact';
+
+    /**
+     * One thing a call touched, as recorded on the `capability.audited`
+     * event's payload under `subjects`.
+     *
+     * Absent rather than empty when the capability declares none, which
+     * is most of them: absence says nobody has decided what this
+     * capability's subjects are, where an empty array would say the call
+     * touched nothing.
+     *
+     * `from` matters and is not bookkeeping. On `llm.invoke` the prompt
+     * is an input (the caller names it, so it is known even when the
+     * call fails) and the model is an output (the instruction class
+     * picks it from its provider chain at call time), so a reader that
+     * ignored this field would read a requested model as a used one.
+     *
+     * `digest` is present only where a capability had a cheap way to
+     * produce one — a `dvc.lock` read hands back a digest beside each
+     * path, a file read does not, and hashing on every `fs.readFile`
+     * would put I/O in the audit path. Its absence downgrades the answer
+     * from integrity to identity; it does not invalidate it.
+     */
+    export interface CapabilitySubject {
+      kind: SubjectKind | string;
+      /** How it is named: a path, a model id, a collection. */
+      id: string;
+      /** Its content digest, when a sibling field declared one. */
+      digest?: string;
+      /** Which side of the call named it. */
+      from: 'input' | 'output';
+    }
+
     /**
      * Capability Gateway API
      */