@workglow/task-graph 0.2.31 → 0.2.32

package/dist/task/EntitlementProfile.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * IEntitlementProfile — runtime-environment view of an entitlement system.
+ * Extends IEntitlementEnforcer with a single-key request API, change-event
+ * subscription, surface introspection, and disposal. Profiles delegate
+ * signal observation to a pluggable IEntitlementSignalSource.
+ */
+import type { EntitlementDenial, IEntitlementEnforcer } from "./EntitlementEnforcer";
+import type { EntitlementPolicy } from "./EntitlementPolicy";
+import type { IEntitlementResolver } from "./EntitlementResolver";
+import type { EntitlementGrant, TaskEntitlement } from "./TaskEntitlements";
+/**
+ * A signal emitted by an external source telling profiles that a permission
+ * may have changed.
+ *
+ * - `revoke`: a previously granted entitlement may now be denied.
+ * - `grant`: a previously denied entitlement may now be granted.
+ * - `reload`: the underlying policy may have changed in arbitrary ways;
+ *   profiles should re-evaluate every entitlement they have been queried
+ *   about.
+ */
+export type EntitlementSignal = {
+    readonly kind: "revoke";
+    readonly entitlement: TaskEntitlement;
+} | {
+    readonly kind: "grant";
+    readonly entitlement: TaskEntitlement;
+} | {
+    readonly kind: "reload";
+};
+/**
+ * Pluggable port that produces signals about external permission changes.
+ * Built-in profiles default to `STATIC_SIGNAL_SOURCE`. Downstream packages
+ * (e.g. workflow-builder Electron) provide implementations that wrap
+ * platform events.
+ */
+export interface IEntitlementSignalSource {
+    /**
+     * Register a listener for signals. The returned function unsubscribes.
+     * Implementations must make the unsubscribe idempotent.
+     */
+    subscribe(listener: (signal: EntitlementSignal) => void): () => void;
+}
+/** Frozen no-op signal source. Never emits; subscribe returns a no-op unsub. */
+export declare const STATIC_SIGNAL_SOURCE: IEntitlementSignalSource;
+/**
+ * Result of `requestEntitlement(required)`. Discriminated union on `outcome`.
+ *
+ * Optional entitlements always map to `outcome: "granted"` regardless of the
+ * underlying policy verdict — matching the rule that optional entitlements
+ * are filtered out of `IEntitlementEnforcer.checkAll`.
+ *
+ * `"ask"` policy verdicts are resolved internally via the registered
+ * `IEntitlementResolver` before this function returns; callers only ever
+ * see `"granted"` or `"denied"`.
+ */
+export type EntitlementRequestResult = {
+    readonly outcome: "granted";
+    readonly entitlement: TaskEntitlement;
+} | {
+    readonly outcome: "denied";
+    readonly denial: EntitlementDenial;
+};
+/**
+ * Emitted by an `IEntitlementProfile` when a previously-observed entitlement
+ * verdict transitions. Profiles only emit events for entitlements whose
+ * verdict actually flipped between two queries.
+ */
+export type EntitlementChangeEvent = {
+    readonly kind: "revoked" | "granted";
+    readonly entitlement: TaskEntitlement;
+};
+/**
+ * Runtime-environment view of an entitlement system.
+ *
+ * Extends `IEntitlementEnforcer` with:
+ * - `name`: free-form identifier for diagnostics.
+ * - `surface()`: maximum set of entitlements this profile may grant.
+ * - `requestEntitlement()`: single-key request returning a discriminated verdict.
+ * - `subscribe()`: observe change events from the bound signal source.
+ * - `dispose()`: idempotent teardown including signal-source unsubscribe.
+ */
+export interface IEntitlementProfile extends IEntitlementEnforcer {
+    /** Free-form identifier (e.g. "browser", "desktop", "server"). */
+    readonly name: string;
+    /**
+     * The maximum set of grants this profile may issue.
+     *
+     * Implementations MAY return a live view of the underlying policy's
+     * grant array — callers must not mutate the returned array. Treat the
+     * return value as `Readonly<readonly EntitlementGrant[]>` even though
+     * `Object.freeze` is not guaranteed.
+     */
+    surface(): readonly EntitlementGrant[];
+    /** Single-key request. See `EntitlementRequestResult`. */
+    requestEntitlement(required: TaskEntitlement): Promise<EntitlementRequestResult>;
+    /** Subscribe to change events. The returned unsubscribe must be idempotent. */
+    subscribe(listener: (event: EntitlementChangeEvent) => void): () => void;
+    /** Idempotent teardown. */
+    dispose(): Promise<void>;
+}
+export interface CreateProfileOptions {
+    readonly resolver?: IEntitlementResolver;
+    /** Defaults to `STATIC_SIGNAL_SOURCE`. */
+    readonly signalSource?: IEntitlementSignalSource;
+}
+/**
+ * Build an `IEntitlementProfile` from a policy.
+ *
+ * Wraps `createPolicyEnforcer` and adds:
+ * - `surface()` returning the policy's grants
+ * - `requestEntitlement()` reusing `checkAll` for a single entitlement
+ * - signal-source subscription with verdict-flip change events
+ * - idempotent `dispose()`
+ *
+ * The "previously queried" set used to scope `reload` events is private to
+ * the profile and cleared on `dispose`.
+ */
+export declare function createPolicyProfile(name: string, policy: EntitlementPolicy, options?: CreateProfileOptions): IEntitlementProfile;
+/**
+ * Service token for registering an `IEntitlementProfile`.
+ *
+ * Distinct from `ENTITLEMENT_ENFORCER`: a profile exposes a richer surface
+ * (subscribe + dispose + surface). `ServiceRegistry` resolves by token
+ * identity, so a registration under `ENTITLEMENT_PROFILE` is NOT
+ * automatically visible to consumers resolving `ENTITLEMENT_ENFORCER`.
+ *
+ * Because `IEntitlementProfile extends IEntitlementEnforcer`, the same
+ * profile instance can be registered under both tokens if both consumer
+ * styles need to resolve it.
+ */
+export declare const ENTITLEMENT_PROFILE: import("@workglow/util").ServiceToken<IEntitlementProfile>;
+//# sourceMappingURL=EntitlementProfile.d.ts.map

package/dist/task/EntitlementProfile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntitlementProfile.d.ts","sourceRoot":"","sources":["../../src/task/EntitlementProfile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACrF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAM5E;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAA;CAAE,GAClE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAA;CAAE,GACjE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACtE;AAED,gFAAgF;AAChF,eAAO,MAAM,oBAAoB,EAAE,wBAMjC,CAAC;AAMH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAA;CAAE,GACtE;IAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAMvE;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;CACvC,CAAC;AAMF;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAoB,SAAQ,oBAAoB;IAC/D,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,OAAO,IAAI,SAAS,gBAAgB,EAAE,CAAC;IACvC,0DAA0D;IAC1D,kBAAkB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;IACjF,+EAA+E;IAC/E,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACzE,2BAA2B;IAC3B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAMD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IACzC,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,CAAC,EAAE,wBAAwB,CAAC;CAClD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,oBAAyB,GACjC,mBAAmB,CAiHrB;AAMD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,4DAE/B,CAAC"}

package/dist/task/EntitlementProfiles.d.ts

@@ -7,9 +7,8 @@
  * The library has no concept of Electron, brands, or deployment targets —
  * only capability profiles expressed as entitlement policies.
  */
-import { type IEntitlementEnforcer } from "./EntitlementEnforcer";
+import { type CreateProfileOptions, type IEntitlementProfile } from "./EntitlementProfile";
 import type { EntitlementPolicy } from "./EntitlementPolicy";
-import type { IEntitlementResolver } from "./EntitlementResolver";
 import type { EntitlementGrant } from "./TaskEntitlements";
 /**
  * Browser environment grants.
@@ -41,13 +40,14 @@ export type EntitlementProfile = "browser" | "desktop" | "server";
  */
 export declare function createProfilePolicy(profile: EntitlementProfile): EntitlementPolicy;
 /**
- * Creates an entitlement enforcer for the given runtime profile.
- * Tasks requiring entitlements not in the profile will be denied.
+ * Creates an entitlement profile for the given runtime profile.
+ * The profile's grants become the policy's grant rules.
+ * Deny and ask arrays are empty by default — callers can extend the returned profile.
  *
  * @param profile - The runtime profile to use
- * @param resolver - Optional resolver for handling "ask" verdicts
+ * @param options - Optional resolver (for "ask" verdicts) and signal source
  */
-export declare function createProfileEnforcer(profile: EntitlementProfile, resolver?: IEntitlementResolver): IEntitlementEnforcer;
+export declare function createProfileEnforcer(profile: EntitlementProfile, options?: CreateProfileOptions): IEntitlementProfile;
 /**
  * Returns the grant list for a given profile.
  * Useful for inspection or combining with additional grants.

package/dist/task/EntitlementProfiles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EntitlementProfiles.d.ts","sourceRoot":"","sources":["../../src/task/EntitlementProfiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAwB,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACxF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAO3D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,gBAAgB,EASrD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,gBAAgB,EAUrD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,gBAAgB,EAGpD,CAAC;AAMF,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAQlE;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,kBAAkB,GAAG,iBAAiB,CAElF;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,CAAC,EAAE,oBAAoB,GAC9B,oBAAoB,CAEtB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,GAAG,SAAS,gBAAgB,EAAE,CAEzF"}
+{"version":3,"file":"EntitlementProfiles.d.ts","sourceRoot":"","sources":["../../src/task/EntitlementProfiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAO3D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,gBAAgB,EASrD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,gBAAgB,EAUrD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,gBAAgB,EAGpD,CAAC;AAMF,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAQlE;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,kBAAkB,GAAG,iBAAiB,CAElF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,mBAAmB,CAErB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,GAAG,SAAS,gBAAgB,EAAE,CAEzF"}

package/dist/task/index.d.ts

@@ -7,6 +7,7 @@ export * from "./ConditionalTask";
 export * from "./ConditionUtils";
 export * from "./EntitlementEnforcer";
 export * from "./EntitlementPolicy";
+export * from "./EntitlementProfile";
 export * from "./EntitlementProfiles";
 export * from "./EntitlementResolver";
 export * from "./FallbackTask";

package/dist/task/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/task/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,QAAQ,CAAC;AACvB,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAElC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,eAAO,MAAM,iBAAiB,qIAI7B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/task/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,QAAQ,CAAC;AACvB,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAElC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,eAAO,MAAM,iBAAiB,qIAI7B,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@workglow/task-graph",
   "type": "module",
-  "version": "0.2.31",
+  "version": "0.2.32",
   "repository": {
     "type": "git",
     "url": "https://github.com/workglow-dev/workglow.git",
@@ -51,9 +51,9 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@workglow/job-queue": "0.2.31",
-    "@workglow/storage": "0.2.31",
-    "@workglow/util": "0.2.31"
+    "@workglow/job-queue": "0.2.32",
+    "@workglow/storage": "0.2.32",
+    "@workglow/util": "0.2.32"
   },
   "peerDependenciesMeta": {
     "@workglow/job-queue": {
@@ -67,8 +67,8 @@
     }
   },
   "devDependencies": {
-    "@workglow/job-queue": "0.2.31",
-    "@workglow/storage": "0.2.31",
-    "@workglow/util": "0.2.31"
+    "@workglow/job-queue": "0.2.32",
+    "@workglow/storage": "0.2.32",
+    "@workglow/util": "0.2.32"
   }
 }