@punica/editor 1.41.1 → 1.43.0

package/package.json

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

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

@@ -66,6 +66,24 @@ declare module 'punica' {
          * choice, and `approvePending` clamps a wider one to it.
          */
         maxScope?: ApprovalScope;
+        /**
+         * Who may answer (`kernel.PolicyRequest.approvers`). A card whose
+         * host identity matches no entry offers no grant and asks a
+         * reviewer instead.
+         */
+        approvers?: readonly string[];
+        /**
+         * The organisation those approvers hold their roles in
+         * (`kernel.PolicyRequest.org`), so a host that asks a reviewer
+         * asks the right one. Absent means the file named none.
+         */
+        org?: string;
+        /**
+         * Set by `referPending`: the question was handed to a reviewer
+         * outside this host, under this name. A run waiting on it holds
+         * for the reviewer's answer instead of timing out.
+         */
+        referredTo?: string;
         correlationId?: string;
         /**
          * Trace id of the invocation that hit the gate (an agent run id
@@ -760,8 +778,29 @@ declare module 'punica' {
         runLastPlan(editedPlan?: AiPlan): Promise<AiRun>;
         getLastPlan(): AiPlan | null;
         getPendingApprovals(): PendingApproval[];
-        approvePending(pendingId: string, scope: kernel.ApprovalScope): boolean;
-        dismissPending(pendingId: string): boolean;
+        /**
+         * Record the grant a person made. `decider` names who, when the
+         * decision was made elsewhere and relayed by the host (a reviewer
+         * answering through the registry); absent, the host identity
+         * decides. Throws `APPROVER_NOT_ALLOWED` when the pending names
+         * approvers and the decider is none of them.
+         */
+        approvePending(
+          pendingId: string,
+          scope: kernel.ApprovalScope,
+          decider?: { decidedBy?: string; decidedRole?: string }
+        ): boolean;
+        dismissPending(
+          pendingId: string,
+          decider?: { decidedBy?: string; decidedRole?: string; reason?: string }
+        ): boolean;
+        /**
+         * Hand a pending question to a reviewer outside this host, by
+         * name (`role:ml-lead`, `user:<email>`, `owner`). Writes nothing
+         * to the store; publishes `ai.pendingApprovalReferred` so the run
+         * that asked waits for the answer instead of timing out.
+         */
+        referPending(pendingId: string, to: string): boolean;
         /**
          * Hand a pending question back with different arguments. No grant
          * and no decline is written; the loop that asked dispatches again

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

@@ -72,6 +72,19 @@ declare module 'punica' {
        * wider grant. Absent means the approver chooses.
        */
       maxScope?: ApprovalScope;
+      /**
+       * Who may answer, from the deciding rule's `approvers:` (set by the
+       * gate from `PolicyDecision.approvers`, like `maxScope`). A grant is
+       * consulted and recorded only under a decider one entry names;
+       * absent means anyone at this host may decide.
+       */
+      approvers?: readonly string[];
+      /**
+       * The organisation those approvers hold their roles in, from the
+       * file's `org:`. A role then counts only there; absent means a
+       * role in any of the person's organisations counts.
+       */
+      org?: string;
     }
 
     /**
@@ -165,6 +178,12 @@ declare module 'punica' {
       approval: PolicyApproval;
       reason?: string;
       decidedBy?: string;
+      /**
+       * Under which name the decider satisfied the rule's `approvers:`
+       * (`owner`, `role:ml-lead`, `user:<email>`). Absent on a grant no
+       * rule named approvers for.
+       */
+      decidedRole?: string;
       timestampMs: number;
       /**
        * Optional chain reference — Sub-step 3.L. When present,
@@ -209,6 +228,10 @@ declare module 'punica' {
        * when no rule wrote one.
        */
       maxScope?: ApprovalScope;
+      /** The deciding `require` rule's `approvers:`, when it wrote them. */
+      approvers?: readonly string[];
+      /** The organisation those approvers hold their roles in (the file's `org:`). */
+      org?: string;
       reason?: string;
       /**
        * Set when a rule from a policy template decided this. Absent
@@ -284,6 +307,15 @@ declare module 'punica' {
         ctx?: {
           workspaceId?: string;
           decidedBy?: string;
+          /**
+           * The name the decider decides under, when a trusted caller
+           * relays a decision made elsewhere (a reviewer answering
+           * through the registry): `owner`, `role:<name>` or
+           * `user:<email>`. With `req.approvers` set and this absent,
+           * the host identity's roles are matched instead; a decider
+           * no entry names is refused with `APPROVER_NOT_ALLOWED`.
+           */
+          decidedRole?: string;
           /**
            * Time-bound the approval — Sub-step 3.F. Epoch ms;
            * `hasApproval` rejects after this point. Undefined =
@@ -328,6 +360,8 @@ declare module 'punica' {
         ctx?: {
           workspaceId?: string;
           decidedBy?: string;
+          /** As on `recordApproval`: the name a relayed decider decided under. */
+          decidedRole?: string;
           /** Why, in the decider's words. Stored verbatim. */
           reason?: string;
           traceId?: string;
@@ -506,6 +540,15 @@ declare module 'punica' {
        * effect on the next call without anyone revoking anything.
        */
       scope?: ApprovalScope;
+      /**
+       * Who may answer, only on `effect: 'require'`: `owner`,
+       * `role:<name>` or `user:<email>`, any one of which is enough. A
+       * grant recorded by anyone else does not satisfy the rule, and a
+       * host whose identity matches no entry cannot grant it — it asks
+       * a reviewer instead. Absent means anyone at the host decides,
+       * which is what every rule written before this field meant.
+       */
+      approvers?: string[];
       /** Shown to the user on a denial and written into the audit record. */
       reason?: string;
     }
@@ -520,6 +563,10 @@ declare module 'punica' {
       reason?: string;
       /** The rule's `scope`, when it wrote one (`effect: require` only). */
       scope?: ApprovalScope;
+      /** The rule's `approvers`, when it wrote them (`effect: require` only). */
+      approvers?: string[];
+      /** The file's `org:`, when it wrote one — where those approvers hold their roles. */
+      org?: string;
       /** Digest of the template's rules — which policy text was in force. */
       digest?: string;
       /**
@@ -557,6 +604,12 @@ declare module 'punica' {
       name: string;
       description?: string;
       workspaceId?: string;
+      /**
+       * The file's `org:` — the organisation the rules' `approvers:`
+       * resolve against. Set by the loader on every template of a file
+       * that wrote it, and carried onto each rule's ref.
+       */
+      org?: string;
       rules: PolicyRule[];
       /**
        * Where the template came from. `file` templates are owned by

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

@@ -235,6 +235,13 @@ declare module 'punica' {
        * invents nothing to fill it. Passing `undefined` clears it.
        */
       setHostIdentity: (identity: HostIdentity | undefined) => void;
+      /**
+       * The identity the host injected, or `undefined`. Read by a card
+       * deciding whether the person at this host may answer a rule that
+       * names its approvers (`roles`), and by a host asking a reviewer
+       * (`orgs`). Never a substitute for the audit record's `actor.id`.
+       */
+      getHostIdentity: () => HostIdentity | undefined;
 
       /**
        * Package signing. A host installs a signer during bootstrap so an
@@ -395,6 +402,15 @@ declare module 'punica' {
     export interface HostIdentity {
       email: string;
       displayName?: string | null;
+      /**
+       * The person's organisation roles, as the registry lists them
+       * (`owner`, `ml-lead`, …), across every organisation they belong
+       * to. Read by a `require` rule that names its `approvers:`; absent
+       * or empty means such a rule matches nobody at this host.
+       */
+      roles?: readonly string[];
+      /** The organisations behind those roles, for a host that asks a reviewer. */
+      orgs?: ReadonlyArray<{ id: string; name: string; role: string }>;
     }
 
     /**