@punica/editor 1.19.3 → 1.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punica/editor",
-  "version": "1.19.3",
+  "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.api.d.ts

@@ -212,6 +212,22 @@ declare module 'punica' {
         verifier: kernel.ApprovalTokenVerifier | undefined
       ) => void;
 
+      /**
+       * The signer and verifier currently in force — the injected pair, or
+       * the substrate's ephemeral default when a host installed none.
+       *
+       * Declared because the setters above do not work without them. The
+       * getter is the only reader of the module's active-signer binding, so
+       * with it unreachable the build eliminated the binding, and
+       * `setApprovalTokenSigner` compiled down to an empty function: a host
+       * could install a KMS signer and have it silently discarded, while
+       * `installDefaultApprovalTokenPair` installed only the verifier half.
+       * A seam is not reachable because a function exists; it is reachable
+       * when something published reads what it writes.
+       */
+      getApprovalTokenSigner: () => kernel.ApprovalTokenSigner;
+      getApprovalTokenVerifier: () => kernel.ApprovalTokenVerifier;
+
       /**
        * Who is at this workstation, so a user-initiated call's audit record
        * names a subject instead of leaving `actor.id` empty. Absent is a
@@ -219,6 +235,48 @@ declare module 'punica' {
        * invents nothing to fill it. Passing `undefined` clears it.
        */
       setHostIdentity: (identity: HostIdentity | undefined) => void;
+
+      /**
+       * Package signing. A host installs a signer during bootstrap so an
+       * evidence package can carry a signature a reader is able to check:
+       *
+       *   punica.runtime.setPackageSigner(signer)
+       *
+       * **There is no substrate default, deliberately.** The approval-token
+       * seam above ships an ephemeral fallback, and a host that forgets to
+       * inject a stable signer still gets signatures — ones that stop
+       * verifying at the next launch, silently. A signature nobody can verify
+       * is worse than none, because it reads as one. With no signer installed
+       * `signing.sign` refuses and a package states that it is unsigned.
+       *
+       * Passing `undefined` clears it. The key belongs to the host and never
+       * to an extension: an extension that can reach the signing key can also
+       * produce the thing it signs.
+       */
+      setPackageSigner: (signer: PackageSigner | undefined) => void;
+
+      /**
+       * Is this installation able to sign at all? Answers without provoking
+       * the refusal, so a package builder can choose between producing an
+       * unsigned package and failing.
+       */
+      hasPackageSigner: () => boolean;
+
+      /**
+       * Verify a detached package signature. **Pure** — no host seam and no
+       * private key, so a machine that never produced the package (and could
+       * not have) still answers whether the bytes were altered. That is the
+       * property the asymmetric key is bought for.
+       *
+       * Returns `false` for every negative outcome, malformed input included:
+       * "could not check" and "checked and wrong" are the same answer to a
+       * caller, and throwing would tempt a consumer into reading the first as
+       * "checked and fine".
+       */
+      verifyPackageSignature: (
+        bytes: Uint8Array,
+        signature: PackageSignature
+      ) => Promise<boolean>;
     }
 
     /**
@@ -231,6 +289,54 @@ declare module 'punica' {
       displayName?: string | null;
     }
 
+    /**
+     * A detached signature over a package's bytes.
+     *
+     * Asymmetric on purpose. The substrate's other signer — the approval
+     * token — is HMAC over a shared secret, which can only be verified by
+     * whoever holds that secret, and whoever holds it could have produced the
+     * tag themselves. A package is meant to be handed to someone else, so it
+     * is signed with a key whose public half travels inside the signature and
+     * whose private half never leaves the host.
+     *
+     * **What it proves:** integrity — these bytes are the bytes that were
+     * signed. **What it does not prove:** authenticity — nothing vouches for
+     * the public key, because the machine that produces a package is the
+     * machine that signs it. `selfSigned` carries that limit so a consumer
+     * states it rather than implying more.
+     */
+    export interface PackageSignature {
+      /** ECDSA P-256 with SHA-256. Chosen over Ed25519 for WebCrypto reach. */
+      alg: 'ES256';
+      /** The public half, so any reader can verify without a shared secret. */
+      publicKeyJwk: JsonWebKey;
+      /** SHA-256 over the JWK's canonical coordinates, base64url. */
+      keyId: string;
+      /** The detached signature, base64url. */
+      signature: string;
+      /** When it was produced, epoch ms, as the signing host saw it. */
+      signedAt: number;
+      /** Always true today; integrity verifies, authenticity does not. */
+      selfSigned: true;
+    }
+
+    /**
+     * The host-injected half of package signing. Implemented by the host, not
+     * by the substrate and never by an extension.
+     */
+    export interface PackageSigner {
+      /**
+       * Sign `bytes`. The implementation prefixes a protocol context string
+       * before the key sees them, so a signature made here cannot be replayed
+       * as one made for a different protocol.
+       */
+      sign(bytes: Uint8Array): Promise<PackageSignature>;
+      /** The public key, for a package header written before signing. */
+      publicKey(): Promise<
+        Pick<PackageSignature, 'alg' | 'publicKeyJwk' | 'keyId'>
+      >;
+    }
+
   }
 
   export const runtime: runtime.RuntimeApi;

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
      */