@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/organizations/organization-unit-narrowing-decision.shared.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The single authority deciding whether — and how — a request is narrowed by organization unit.
+ *
+ * ## Why one function rather than two checks
+ *
+ * The decision is consumed in two places that live in different services: the OPERATION GATE (may
+ * this caller attempt this at all?) and the ROW FILTER / WRITE VALIDATION (which rows may they
+ * touch?). Those must agree exactly. If the gate admits a caller on the strength of a unit grant and
+ * the filter then fails to narrow, that unit grant has silently become organization-wide access —
+ * the precise escalation the narrowing model exists to avoid. Deriving both from one function makes
+ * disagreement impossible rather than merely unlikely.
+ *
+ * It is also the "record the conferring grant" surface: the returned decision names WHY access was
+ * allowed, which is what an access review needs in order to answer "why does this person have access
+ * to this record?".
+ *
+ * ## The algebra (plan decision D-C3b — ADDITIVE)
+ *
+ * Unit grants ADD reach; they never subtract. An organization-wide grant that already satisfies the
+ * operation wins outright and is not narrowed — so opting a resource in can never shrink a result
+ * set that a principal could already see.
+ */
+import type { ExecutionContext_RoleInfo } from '../runtime/execution-context.shared.schemas';
+import { ResourcePrimaryScope } from '../resources/resources.shared.schemas';
+import type { OrganizationUnitNarrowingDeclaration } from './organization-unit-narrowing.shared';
+/** Why a request was allowed — or that it was not. */
+export declare enum OrganizationUnitNarrowingDecisionKind {
+    /** The resource does not participate in unit narrowing; authorization proceeds unchanged. */
+    NOT_NARROWED = "NOT_NARROWED",
+    /** An organization-wide grant satisfies the operation. No narrowing applies (additive). */
+    ORGANIZATION_WIDE = "ORGANIZATION_WIDE",
+    /** ONLY unit grants satisfy the operation, so access is confined to those units. */
+    UNIT_NARROWED = "UNIT_NARROWED",
+    /** Neither an organization-wide nor a unit grant satisfies the operation. */
+    DENIED = "DENIED"
+}
+export type OrganizationUnitNarrowingDecision = {
+    kind: OrganizationUnitNarrowingDecisionKind.NOT_NARROWED;
+} | {
+    kind: OrganizationUnitNarrowingDecisionKind.ORGANIZATION_WIDE;
+} | {
+    kind: OrganizationUnitNarrowingDecisionKind.UNIT_NARROWED;
+    unitFieldName: string;
+    organizationUnitIds: string[];
+} | {
+    kind: OrganizationUnitNarrowingDecisionKind.DENIED;
+};
+/**
+ * A decision as STAMPED on an execution context — the conferring-grant record.
+ *
+ * assurance-control: WILDO.ACCESS.SCOPE_CONFINEMENT — records WHY a principal reached a
+ * record, which is the input an access review needs to answer "why does this person have access to
+ * this?" without reconstructing it from role tables.
+ *
+ * The extra fields beyond {@link decision} exist for that review, not for the runtime rule: the
+ * runtime only ever reads `decision`. `requiredRoles` is what the operation demanded and
+ * `operationIdentifier` is what was attempted, so a reviewer can see the demand, the answer and the
+ * units it resolved to in one record.
+ */
+export type OrganizationUnitNarrowingStamp = {
+    /** The resource the decision was computed FOR. A stamp is only ever valid for this resource. */
+    readonly resourceType: string;
+    /** The operation whose role set was evaluated. Diagnostic/audit only — never a lookup key. */
+    readonly operationIdentifier: string;
+    /** The operation's declared role set at evaluation time. */
+    readonly requiredRoles: readonly string[];
+    /** The decision itself — the only field the runtime rule reads. */
+    readonly decision: OrganizationUnitNarrowingDecision;
+    /**
+     * Of the units in a `UNIT_NARROWED` decision, the ones reached ONLY through downward inheritance
+     * rather than held directly.
+     *
+     * Audit-only, and the reason it exists is specific: with `INHERIT_DOWN`, a grant at a ROOT unit
+     * reaches the entire organization chart — functionally organization-wide access assembled from one
+     * narrow grant (plan decision D-C4, watch item 4). Reporting only the effective set would make that
+     * indistinguishable from a genuinely narrow grant in the access record. Splitting it lets a reviewer
+     * see "granted at Sales, effective across Sales and 12 descendants" and judge whether that is what
+     * was intended.
+     */
+    readonly inheritedOrganizationUnitIds?: readonly string[];
+};
+/**
+ * Combine an existing stamp with a new one for the SAME resource — a stamp may only ever TIGHTEN.
+ *
+ * ## Why this is not "last write wins", and not "throw on conflict"
+ *
+ * The execution context is reachable by any backend code holding it, so a plain overwrite would let
+ * a later `ORGANIZATION_WIDE` stamp erase an earlier `UNIT_NARROWED` one and lift the narrowing —
+ * the same privilege-escalation surface the retention see-through setter is guarded against.
+ * Throwing on a conflict was rejected instead: the gate is legitimately re-entered within one request
+ * (field-validation pre-checks, the MCP tool dispatcher re-running the controller gate), and turning
+ * a legitimate re-entry into an exception converts a safe situation into a 500.
+ *
+ * Monotonic tightening satisfies both: a second evaluation can restrict further, never widen. Two
+ * `UNIT_NARROWED` stamps INTERSECT their unit sets for the same reason.
+ *
+ * The cost is deliberate over-restriction in one edge case: if two operations on the same resource
+ * within one request legitimately resolve differently (one satisfied organization-wide, one only by a
+ * unit grant), the narrower answer governs both. That is the fail-safe direction.
+ */
+export declare function mergeOrganizationUnitNarrowingStamps(existingStamp: OrganizationUnitNarrowingStamp | undefined, incomingStamp: OrganizationUnitNarrowingStamp): OrganizationUnitNarrowingStamp;
+/** Expands one role into everything it confers within a scope — the runtime `inheritFrom` chain. */
+export type OrganizationUnitRoleHierarchyResolver = (role: string, scope: ResourcePrimaryScope) => string[];
+/**
+ * Decide the narrowing posture for one request.
+ *
+ * `requiredRoles` is the operation's declared role set. An operation declaring NO roles is not
+ * treated as "anyone passes" here — this function only ever ANSWERS the unit question, and returns
+ * {@link OrganizationUnitNarrowingDecisionKind.NOT_NARROWED} so the caller's existing authorization
+ * logic remains the authority for every non-unit consideration.
+ *
+ * Evaluation order encodes the additive rule:
+ *   1. resource not opted in            → NOT_NARROWED (nothing to say)
+ *   2. organization-wide grant suffices → ORGANIZATION_WIDE (widest wins; no narrowing)
+ *   3. unit grant suffices              → UNIT_NARROWED, confined to the units that supplied it
+ *   4. otherwise                        → DENIED
+ *
+ * Step 3 confines access to the units whose grant ACTUALLY satisfied the operation, not to every
+ * unit the principal belongs to. A member who is ORG_MANAGER of Sales and ORG_GUEST of Legal, acting
+ * on a MANAGER-gated operation, reaches Sales only — carrying Legal along would grant reach that no
+ * held role justifies.
+ */
+export declare function resolveOrganizationUnitNarrowingDecision(input: {
+    readonly resourceType: string;
+    readonly requiredRoles: readonly string[];
+    readonly initiatorRoles: readonly ExecutionContext_RoleInfo[] | undefined;
+    readonly narrowingRegistry: Readonly<Partial<Record<string, OrganizationUnitNarrowingDeclaration>>>;
+    readonly roleHierarchyResolver: OrganizationUnitRoleHierarchyResolver;
+}): OrganizationUnitNarrowingDecision;
+//# sourceMappingURL=organization-unit-narrowing-decision.shared.d.ts.map

package/dist/esm/organizations/organization-unit-narrowing-decision.shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"organization-unit-narrowing-decision.shared.d.ts","sourceRoot":"","sources":["../../../../src/organizations/organization-unit-narrowing-decision.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,6CAA6C,CAAC;AAE7F,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,KAAK,EAAE,oCAAoC,EAAE,MAAM,sCAAsC,CAAC;AAGjG,sDAAsD;AACtD,oBAAY,qCAAqC;IAC/C,6FAA6F;IAC7F,YAAY,iBAAiB;IAC7B,2FAA2F;IAC3F,iBAAiB,sBAAsB;IACvC,oFAAoF;IACpF,aAAa,kBAAkB;IAC/B,6EAA6E;IAC7E,MAAM,WAAW;CAClB;AAED,MAAM,MAAM,iCAAiC,GACzC;IAAE,IAAI,EAAE,qCAAqC,CAAC,YAAY,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,qCAAqC,CAAC,iBAAiB,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,qCAAqC,CAAC,aAAa,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,mBAAmB,EAAE,MAAM,EAAE,CAAA;CAAE,GACnH;IAAE,IAAI,EAAE,qCAAqC,CAAC,MAAM,CAAA;CAAE,CAAC;AAE3D;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,gGAAgG;IAChG,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,8FAA8F;IAC9F,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,iCAAiC,CAAC;IACrD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,4BAA4B,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3D,CAAC;AAaF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oCAAoC,CAClD,aAAa,EAAE,8BAA8B,GAAG,SAAS,EACzD,aAAa,EAAE,8BAA8B,GAC5C,8BAA8B,CAwBhC;AAED,oGAAoG;AACpG,MAAM,MAAM,qCAAqC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,KAAK,MAAM,EAAE,CAAC;AAc5G;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wCAAwC,CAAC,KAAK,EAAE;IAC9D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,cAAc,EAAE,SAAS,yBAAyB,EAAE,GAAG,SAAS,CAAC;IAC1E,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,oCAAoC,CAAC,CAAC,CAAC,CAAC;IACpG,QAAQ,CAAC,qBAAqB,EAAE,qCAAqC,CAAC;CACvE,GAAG,iCAAiC,CA6BpC"}

package/dist/esm/organizations/organization-unit-narrowing-decision.shared.js

@@ -0,0 +1,139 @@
+/**
+ * The single authority deciding whether — and how — a request is narrowed by organization unit.
+ *
+ * ## Why one function rather than two checks
+ *
+ * The decision is consumed in two places that live in different services: the OPERATION GATE (may
+ * this caller attempt this at all?) and the ROW FILTER / WRITE VALIDATION (which rows may they
+ * touch?). Those must agree exactly. If the gate admits a caller on the strength of a unit grant and
+ * the filter then fails to narrow, that unit grant has silently become organization-wide access —
+ * the precise escalation the narrowing model exists to avoid. Deriving both from one function makes
+ * disagreement impossible rather than merely unlikely.
+ *
+ * It is also the "record the conferring grant" surface: the returned decision names WHY access was
+ * allowed, which is what an access review needs in order to answer "why does this person have access
+ * to this record?".
+ *
+ * ## The algebra (plan decision D-C3b — ADDITIVE)
+ *
+ * Unit grants ADD reach; they never subtract. An organization-wide grant that already satisfies the
+ * operation wins outright and is not narrowed — so opting a resource in can never shrink a result
+ * set that a principal could already see.
+ */
+import { isOrganizationWideRoleInfo, selectUnitScopedRoleGrants } from '../runtime/execution-context.shared.schemas.js';
+import { ResourcePrimaryScope } from '../resources/resources.shared.schemas.js';
+import { resolveOrganizationUnitNarrowing } from './organization-unit-narrowing.shared.js';
+/** Why a request was allowed — or that it was not. */
+export var OrganizationUnitNarrowingDecisionKind;
+(function (OrganizationUnitNarrowingDecisionKind) {
+    /** The resource does not participate in unit narrowing; authorization proceeds unchanged. */
+    OrganizationUnitNarrowingDecisionKind["NOT_NARROWED"] = "NOT_NARROWED";
+    /** An organization-wide grant satisfies the operation. No narrowing applies (additive). */
+    OrganizationUnitNarrowingDecisionKind["ORGANIZATION_WIDE"] = "ORGANIZATION_WIDE";
+    /** ONLY unit grants satisfy the operation, so access is confined to those units. */
+    OrganizationUnitNarrowingDecisionKind["UNIT_NARROWED"] = "UNIT_NARROWED";
+    /** Neither an organization-wide nor a unit grant satisfies the operation. */
+    OrganizationUnitNarrowingDecisionKind["DENIED"] = "DENIED";
+})(OrganizationUnitNarrowingDecisionKind || (OrganizationUnitNarrowingDecisionKind = {}));
+/**
+ * How restrictive a decision is. Higher wins when two stamps meet — see
+ * {@link mergeOrganizationUnitNarrowingStamps}.
+ */
+const NARROWING_RESTRICTIVENESS = {
+    [OrganizationUnitNarrowingDecisionKind.NOT_NARROWED]: 0,
+    [OrganizationUnitNarrowingDecisionKind.ORGANIZATION_WIDE]: 0,
+    [OrganizationUnitNarrowingDecisionKind.UNIT_NARROWED]: 1,
+    [OrganizationUnitNarrowingDecisionKind.DENIED]: 2,
+};
+/**
+ * Combine an existing stamp with a new one for the SAME resource — a stamp may only ever TIGHTEN.
+ *
+ * ## Why this is not "last write wins", and not "throw on conflict"
+ *
+ * The execution context is reachable by any backend code holding it, so a plain overwrite would let
+ * a later `ORGANIZATION_WIDE` stamp erase an earlier `UNIT_NARROWED` one and lift the narrowing —
+ * the same privilege-escalation surface the retention see-through setter is guarded against.
+ * Throwing on a conflict was rejected instead: the gate is legitimately re-entered within one request
+ * (field-validation pre-checks, the MCP tool dispatcher re-running the controller gate), and turning
+ * a legitimate re-entry into an exception converts a safe situation into a 500.
+ *
+ * Monotonic tightening satisfies both: a second evaluation can restrict further, never widen. Two
+ * `UNIT_NARROWED` stamps INTERSECT their unit sets for the same reason.
+ *
+ * The cost is deliberate over-restriction in one edge case: if two operations on the same resource
+ * within one request legitimately resolve differently (one satisfied organization-wide, one only by a
+ * unit grant), the narrower answer governs both. That is the fail-safe direction.
+ */
+export function mergeOrganizationUnitNarrowingStamps(existingStamp, incomingStamp) {
+    if (!existingStamp)
+        return incomingStamp;
+    const existingWeight = NARROWING_RESTRICTIVENESS[existingStamp.decision.kind];
+    const incomingWeight = NARROWING_RESTRICTIVENESS[incomingStamp.decision.kind];
+    if (existingStamp.decision.kind === OrganizationUnitNarrowingDecisionKind.UNIT_NARROWED &&
+        incomingStamp.decision.kind === OrganizationUnitNarrowingDecisionKind.UNIT_NARROWED) {
+        const existingUnitIds = new Set(existingStamp.decision.organizationUnitIds);
+        const intersectedUnitIds = incomingStamp.decision.organizationUnitIds.filter((unitId) => existingUnitIds.has(unitId));
+        // The audit split follows the intersection: an inherited unit that did not survive is no longer
+        // reached, so reporting it would overstate the grant in the very record a reviewer reads.
+        const survivingIntersectedUnitIds = new Set(intersectedUnitIds);
+        return {
+            ...incomingStamp,
+            decision: { ...incomingStamp.decision, organizationUnitIds: intersectedUnitIds },
+            inheritedOrganizationUnitIds: (incomingStamp.inheritedOrganizationUnitIds ?? []).filter((unitId) => survivingIntersectedUnitIds.has(unitId)),
+        };
+    }
+    return incomingWeight > existingWeight ? incomingStamp : existingStamp;
+}
+/** Does any of `heldRoles` confer at least one of `requiredRoles`, within `scope`? */
+function satisfiesAnyRequiredRole(heldRoles, requiredRoles, scope, roleHierarchyResolver) {
+    if (requiredRoles.length === 0)
+        return false;
+    const conferred = new Set(heldRoles.flatMap((role) => roleHierarchyResolver(role, scope)));
+    return requiredRoles.some((requiredRole) => conferred.has(requiredRole));
+}
+/**
+ * Decide the narrowing posture for one request.
+ *
+ * `requiredRoles` is the operation's declared role set. An operation declaring NO roles is not
+ * treated as "anyone passes" here — this function only ever ANSWERS the unit question, and returns
+ * {@link OrganizationUnitNarrowingDecisionKind.NOT_NARROWED} so the caller's existing authorization
+ * logic remains the authority for every non-unit consideration.
+ *
+ * Evaluation order encodes the additive rule:
+ *   1. resource not opted in            → NOT_NARROWED (nothing to say)
+ *   2. organization-wide grant suffices → ORGANIZATION_WIDE (widest wins; no narrowing)
+ *   3. unit grant suffices              → UNIT_NARROWED, confined to the units that supplied it
+ *   4. otherwise                        → DENIED
+ *
+ * Step 3 confines access to the units whose grant ACTUALLY satisfied the operation, not to every
+ * unit the principal belongs to. A member who is ORG_MANAGER of Sales and ORG_GUEST of Legal, acting
+ * on a MANAGER-gated operation, reaches Sales only — carrying Legal along would grant reach that no
+ * held role justifies.
+ */
+export function resolveOrganizationUnitNarrowingDecision(input) {
+    const { resourceType, requiredRoles, initiatorRoles, narrowingRegistry, roleHierarchyResolver } = input;
+    const narrowing = resolveOrganizationUnitNarrowing(narrowingRegistry, resourceType);
+    if (!narrowing)
+        return { kind: OrganizationUnitNarrowingDecisionKind.NOT_NARROWED };
+    // ADDITIVE: an organization-wide grant that already satisfies the operation wins outright, so
+    // opting a resource in can never shrink what a principal could already see.
+    const organizationWideRoles = (initiatorRoles ?? []).filter(isOrganizationWideRoleInfo);
+    for (const roleInfo of organizationWideRoles) {
+        if (satisfiesAnyRequiredRole(roleInfo.roles, requiredRoles, roleInfo.relatedPrimaryScope, roleHierarchyResolver)) {
+            return { kind: OrganizationUnitNarrowingDecisionKind.ORGANIZATION_WIDE };
+        }
+    }
+    // Only the units whose grant actually satisfies the operation confer reach.
+    const qualifyingUnitIds = selectUnitScopedRoleGrants(initiatorRoles)
+        .filter((grant) => satisfiesAnyRequiredRole(grant.roles, requiredRoles, ResourcePrimaryScope.ORGANIZATIONS, roleHierarchyResolver))
+        .map((grant) => grant.organizationUnitId);
+    if (qualifyingUnitIds.length === 0)
+        return { kind: OrganizationUnitNarrowingDecisionKind.DENIED };
+    return {
+        kind: OrganizationUnitNarrowingDecisionKind.UNIT_NARROWED,
+        unitFieldName: narrowing.unitFieldName,
+        // De-duplicated: several grants can name the same unit, and the value becomes a query predicate.
+        organizationUnitIds: [...new Set(qualifyingUnitIds)],
+    };
+}
+//# sourceMappingURL=organization-unit-narrowing-decision.shared.js.map

package/dist/esm/organizations/organization-unit-narrowing-decision.shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"organization-unit-narrowing-decision.shared.js","sourceRoot":"","sources":["../../../../src/organizations/organization-unit-narrowing-decision.shared.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The single authority deciding whether — and how — a request is narrowed by organization unit.\n *\n * ## Why one function rather than two checks\n *\n * The decision is consumed in two places that live in different services: the OPERATION GATE (may\n * this caller attempt this at all?) and the ROW FILTER / WRITE VALIDATION (which rows may they\n * touch?). Those must agree exactly. If the gate admits a caller on the strength of a unit grant and\n * the filter then fails to narrow, that unit grant has silently become organization-wide access —\n * the precise escalation the narrowing model exists to avoid. Deriving both from one function makes\n * disagreement impossible rather than merely unlikely.\n *\n * It is also the \"record the conferring grant\" surface: the returned decision names WHY access was\n * allowed, which is what an access review needs in order to answer \"why does this person have access\n * to this record?\".\n *\n * ## The algebra (plan decision D-C3b — ADDITIVE)\n *\n * Unit grants ADD reach; they never subtract. An organization-wide grant that already satisfies the\n * operation wins outright and is not narrowed — so opting a resource in can never shrink a result\n * set that a principal could already see.\n */\n\nimport type { ExecutionContext_RoleInfo } from '../runtime/execution-context.shared.schemas';\nimport { isOrganizationWideRoleInfo, selectUnitScopedRoleGrants } from '../runtime/execution-context.shared.schemas';\nimport { ResourcePrimaryScope } from '../resources/resources.shared.schemas';\nimport type { OrganizationUnitNarrowingDeclaration } from './organization-unit-narrowing.shared';\nimport { resolveOrganizationUnitNarrowing } from './organization-unit-narrowing.shared';\n\n/** Why a request was allowed — or that it was not. */\nexport enum OrganizationUnitNarrowingDecisionKind {\n  /** The resource does not participate in unit narrowing; authorization proceeds unchanged. */\n  NOT_NARROWED = 'NOT_NARROWED',\n  /** An organization-wide grant satisfies the operation. No narrowing applies (additive). */\n  ORGANIZATION_WIDE = 'ORGANIZATION_WIDE',\n  /** ONLY unit grants satisfy the operation, so access is confined to those units. */\n  UNIT_NARROWED = 'UNIT_NARROWED',\n  /** Neither an organization-wide nor a unit grant satisfies the operation. */\n  DENIED = 'DENIED',\n}\n\nexport type OrganizationUnitNarrowingDecision =\n  | { kind: OrganizationUnitNarrowingDecisionKind.NOT_NARROWED }\n  | { kind: OrganizationUnitNarrowingDecisionKind.ORGANIZATION_WIDE }\n  | { kind: OrganizationUnitNarrowingDecisionKind.UNIT_NARROWED; unitFieldName: string; organizationUnitIds: string[] }\n  | { kind: OrganizationUnitNarrowingDecisionKind.DENIED };\n\n/**\n * A decision as STAMPED on an execution context — the conferring-grant record.\n *\n * assurance-control: WILDO.ACCESS.SCOPE_CONFINEMENT — records WHY a principal reached a\n * record, which is the input an access review needs to answer \"why does this person have access to\n * this?\" without reconstructing it from role tables.\n *\n * The extra fields beyond {@link decision} exist for that review, not for the runtime rule: the\n * runtime only ever reads `decision`. `requiredRoles` is what the operation demanded and\n * `operationIdentifier` is what was attempted, so a reviewer can see the demand, the answer and the\n * units it resolved to in one record.\n */\nexport type OrganizationUnitNarrowingStamp = {\n  /** The resource the decision was computed FOR. A stamp is only ever valid for this resource. */\n  readonly resourceType: string;\n  /** The operation whose role set was evaluated. Diagnostic/audit only — never a lookup key. */\n  readonly operationIdentifier: string;\n  /** The operation's declared role set at evaluation time. */\n  readonly requiredRoles: readonly string[];\n  /** The decision itself — the only field the runtime rule reads. */\n  readonly decision: OrganizationUnitNarrowingDecision;\n  /**\n   * Of the units in a `UNIT_NARROWED` decision, the ones reached ONLY through downward inheritance\n   * rather than held directly.\n   *\n   * Audit-only, and the reason it exists is specific: with `INHERIT_DOWN`, a grant at a ROOT unit\n   * reaches the entire organization chart — functionally organization-wide access assembled from one\n   * narrow grant (plan decision D-C4, watch item 4). Reporting only the effective set would make that\n   * indistinguishable from a genuinely narrow grant in the access record. Splitting it lets a reviewer\n   * see \"granted at Sales, effective across Sales and 12 descendants\" and judge whether that is what\n   * was intended.\n   */\n  readonly inheritedOrganizationUnitIds?: readonly string[];\n};\n\n/**\n * How restrictive a decision is. Higher wins when two stamps meet — see\n * {@link mergeOrganizationUnitNarrowingStamps}.\n */\nconst NARROWING_RESTRICTIVENESS: Readonly<Record<OrganizationUnitNarrowingDecisionKind, number>> = {\n  [OrganizationUnitNarrowingDecisionKind.NOT_NARROWED]: 0,\n  [OrganizationUnitNarrowingDecisionKind.ORGANIZATION_WIDE]: 0,\n  [OrganizationUnitNarrowingDecisionKind.UNIT_NARROWED]: 1,\n  [OrganizationUnitNarrowingDecisionKind.DENIED]: 2,\n};\n\n/**\n * Combine an existing stamp with a new one for the SAME resource — a stamp may only ever TIGHTEN.\n *\n * ## Why this is not \"last write wins\", and not \"throw on conflict\"\n *\n * The execution context is reachable by any backend code holding it, so a plain overwrite would let\n * a later `ORGANIZATION_WIDE` stamp erase an earlier `UNIT_NARROWED` one and lift the narrowing —\n * the same privilege-escalation surface the retention see-through setter is guarded against.\n * Throwing on a conflict was rejected instead: the gate is legitimately re-entered within one request\n * (field-validation pre-checks, the MCP tool dispatcher re-running the controller gate), and turning\n * a legitimate re-entry into an exception converts a safe situation into a 500.\n *\n * Monotonic tightening satisfies both: a second evaluation can restrict further, never widen. Two\n * `UNIT_NARROWED` stamps INTERSECT their unit sets for the same reason.\n *\n * The cost is deliberate over-restriction in one edge case: if two operations on the same resource\n * within one request legitimately resolve differently (one satisfied organization-wide, one only by a\n * unit grant), the narrower answer governs both. That is the fail-safe direction.\n */\nexport function mergeOrganizationUnitNarrowingStamps(\n  existingStamp: OrganizationUnitNarrowingStamp | undefined,\n  incomingStamp: OrganizationUnitNarrowingStamp,\n): OrganizationUnitNarrowingStamp {\n  if (!existingStamp) return incomingStamp;\n\n  const existingWeight = NARROWING_RESTRICTIVENESS[existingStamp.decision.kind];\n  const incomingWeight = NARROWING_RESTRICTIVENESS[incomingStamp.decision.kind];\n\n  if (\n    existingStamp.decision.kind === OrganizationUnitNarrowingDecisionKind.UNIT_NARROWED &&\n    incomingStamp.decision.kind === OrganizationUnitNarrowingDecisionKind.UNIT_NARROWED\n  ) {\n    const existingUnitIds = new Set(existingStamp.decision.organizationUnitIds);\n    const intersectedUnitIds = incomingStamp.decision.organizationUnitIds.filter((unitId) => existingUnitIds.has(unitId));\n    // The audit split follows the intersection: an inherited unit that did not survive is no longer\n    // reached, so reporting it would overstate the grant in the very record a reviewer reads.\n    const survivingIntersectedUnitIds = new Set(intersectedUnitIds);\n    return {\n      ...incomingStamp,\n      decision: { ...incomingStamp.decision, organizationUnitIds: intersectedUnitIds },\n      inheritedOrganizationUnitIds: (incomingStamp.inheritedOrganizationUnitIds ?? []).filter((unitId) =>\n        survivingIntersectedUnitIds.has(unitId)),\n    };\n  }\n\n  return incomingWeight > existingWeight ? incomingStamp : existingStamp;\n}\n\n/** Expands one role into everything it confers within a scope — the runtime `inheritFrom` chain. */\nexport type OrganizationUnitRoleHierarchyResolver = (role: string, scope: ResourcePrimaryScope) => string[];\n\n/** Does any of `heldRoles` confer at least one of `requiredRoles`, within `scope`? */\nfunction satisfiesAnyRequiredRole(\n  heldRoles: readonly string[],\n  requiredRoles: readonly string[],\n  scope: ResourcePrimaryScope,\n  roleHierarchyResolver: OrganizationUnitRoleHierarchyResolver,\n): boolean {\n  if (requiredRoles.length === 0) return false;\n  const conferred = new Set<string>(heldRoles.flatMap((role) => roleHierarchyResolver(role, scope)));\n  return requiredRoles.some((requiredRole) => conferred.has(requiredRole));\n}\n\n/**\n * Decide the narrowing posture for one request.\n *\n * `requiredRoles` is the operation's declared role set. An operation declaring NO roles is not\n * treated as \"anyone passes\" here — this function only ever ANSWERS the unit question, and returns\n * {@link OrganizationUnitNarrowingDecisionKind.NOT_NARROWED} so the caller's existing authorization\n * logic remains the authority for every non-unit consideration.\n *\n * Evaluation order encodes the additive rule:\n *   1. resource not opted in            → NOT_NARROWED (nothing to say)\n *   2. organization-wide grant suffices → ORGANIZATION_WIDE (widest wins; no narrowing)\n *   3. unit grant suffices              → UNIT_NARROWED, confined to the units that supplied it\n *   4. otherwise                        → DENIED\n *\n * Step 3 confines access to the units whose grant ACTUALLY satisfied the operation, not to every\n * unit the principal belongs to. A member who is ORG_MANAGER of Sales and ORG_GUEST of Legal, acting\n * on a MANAGER-gated operation, reaches Sales only — carrying Legal along would grant reach that no\n * held role justifies.\n */\nexport function resolveOrganizationUnitNarrowingDecision(input: {\n  readonly resourceType: string;\n  readonly requiredRoles: readonly string[];\n  readonly initiatorRoles: readonly ExecutionContext_RoleInfo[] | undefined;\n  readonly narrowingRegistry: Readonly<Partial<Record<string, OrganizationUnitNarrowingDeclaration>>>;\n  readonly roleHierarchyResolver: OrganizationUnitRoleHierarchyResolver;\n}): OrganizationUnitNarrowingDecision {\n  const { resourceType, requiredRoles, initiatorRoles, narrowingRegistry, roleHierarchyResolver } = input;\n\n  const narrowing = resolveOrganizationUnitNarrowing(narrowingRegistry, resourceType);\n  if (!narrowing) return { kind: OrganizationUnitNarrowingDecisionKind.NOT_NARROWED };\n\n  // ADDITIVE: an organization-wide grant that already satisfies the operation wins outright, so\n  // opting a resource in can never shrink what a principal could already see.\n  const organizationWideRoles = (initiatorRoles ?? []).filter(isOrganizationWideRoleInfo);\n  for (const roleInfo of organizationWideRoles) {\n    if (satisfiesAnyRequiredRole(roleInfo.roles, requiredRoles, roleInfo.relatedPrimaryScope, roleHierarchyResolver)) {\n      return { kind: OrganizationUnitNarrowingDecisionKind.ORGANIZATION_WIDE };\n    }\n  }\n\n  // Only the units whose grant actually satisfies the operation confer reach.\n  const qualifyingUnitIds = selectUnitScopedRoleGrants(initiatorRoles)\n    .filter((grant) =>\n      satisfiesAnyRequiredRole(grant.roles, requiredRoles, ResourcePrimaryScope.ORGANIZATIONS, roleHierarchyResolver))\n    .map((grant) => grant.organizationUnitId);\n\n  if (qualifyingUnitIds.length === 0) return { kind: OrganizationUnitNarrowingDecisionKind.DENIED };\n\n  return {\n    kind: OrganizationUnitNarrowingDecisionKind.UNIT_NARROWED,\n    unitFieldName: narrowing.unitFieldName,\n    // De-duplicated: several grants can name the same unit, and the value becomes a query predicate.\n    organizationUnitIds: [...new Set(qualifyingUnitIds)],\n  };\n}\n"]}

package/dist/esm/organizations/organization-unit-narrowing.example.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Illustrative declaration of organization-unit narrowing, for the app-facing skill.
+ *
+ * TIER B (framework-owned illustrative sample): there is no real usage to anchor against — the engine
+ * opts NO resource in, deliberately, and an application's own resource types live outside this
+ * repository. Anchoring a minimal sample beside the contract keeps the skill's worked example
+ * type-checked and in step with the type, rather than drifting as prose in markdown.
+ */
+import type { OrganizationUnitNarrowingDeclaration } from './organization-unit-narrowing.shared';
+/**
+ * @wildo_source:part:start example.authorization.unit-narrowing.declaration facet:kind:usage-example facet:audience:app-developer
+ *
+ * Declaring two of an application's own resources unit-narrowable. This map is passed to application
+ * startup as `organizationUnitNarrowing`.
+ *
+ * Each value names the field on THAT resource holding the owning organization unit's id. The field
+ * must exist on the resource's schema: it becomes a query predicate on every read and a check on
+ * every write, so a misspelled name is an access-control defect rather than a typo.
+ *
+ * Effect: a member whose only qualifying role is inside a unit is admitted for these resources and
+ * confined to that unit's rows (plus its descendants, where the unit inherits downward). A member
+ * whose organization-wide role already satisfies the operation is not narrowed at all — so declaring
+ * this can widen who can reach a resource, never shrink what someone could already see.
+ */
+export declare const exampleOrganizationUnitNarrowing: Readonly<Record<string, OrganizationUnitNarrowingDeclaration>>;
+/** @wildo_source:part:end example.authorization.unit-narrowing.declaration */
+//# sourceMappingURL=organization-unit-narrowing.example.d.ts.map

package/dist/esm/organizations/organization-unit-narrowing.example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"organization-unit-narrowing.example.d.ts","sourceRoot":"","sources":["../../../../src/organizations/organization-unit-narrowing.example.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,oCAAoC,EAAE,MAAM,sCAAsC,CAAC;AAEjG;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gCAAgC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oCAAoC,CAAC,CAG3G,CAAC;AACF,8EAA8E"}

package/dist/esm/organizations/organization-unit-narrowing.example.js

@@ -0,0 +1,29 @@
+/**
+ * Illustrative declaration of organization-unit narrowing, for the app-facing skill.
+ *
+ * TIER B (framework-owned illustrative sample): there is no real usage to anchor against — the engine
+ * opts NO resource in, deliberately, and an application's own resource types live outside this
+ * repository. Anchoring a minimal sample beside the contract keeps the skill's worked example
+ * type-checked and in step with the type, rather than drifting as prose in markdown.
+ */
+/**
+ * @wildo_source:part:start example.authorization.unit-narrowing.declaration facet:kind:usage-example facet:audience:app-developer
+ *
+ * Declaring two of an application's own resources unit-narrowable. This map is passed to application
+ * startup as `organizationUnitNarrowing`.
+ *
+ * Each value names the field on THAT resource holding the owning organization unit's id. The field
+ * must exist on the resource's schema: it becomes a query predicate on every read and a check on
+ * every write, so a misspelled name is an access-control defect rather than a typo.
+ *
+ * Effect: a member whose only qualifying role is inside a unit is admitted for these resources and
+ * confined to that unit's rows (plus its descendants, where the unit inherits downward). A member
+ * whose organization-wide role already satisfies the operation is not narrowed at all — so declaring
+ * this can widen who can reach a resource, never shrink what someone could already see.
+ */
+export const exampleOrganizationUnitNarrowing = {
+    projects: { unitFieldName: 'organizationUnitId' },
+    supportTickets: { unitFieldName: 'owningUnitId' },
+};
+/** @wildo_source:part:end example.authorization.unit-narrowing.declaration */
+//# sourceMappingURL=organization-unit-narrowing.example.js.map

package/dist/esm/organizations/organization-unit-narrowing.example.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"organization-unit-narrowing.example.js","sourceRoot":"","sources":["../../../../src/organizations/organization-unit-narrowing.example.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAmE;IAC9G,QAAQ,EAAE,EAAE,aAAa,EAAE,oBAAoB,EAAE;IACjD,cAAc,EAAE,EAAE,aAAa,EAAE,cAAc,EAAE;CAClD,CAAC;AACF,8EAA8E","sourcesContent":["/**\n * Illustrative declaration of organization-unit narrowing, for the app-facing skill.\n *\n * TIER B (framework-owned illustrative sample): there is no real usage to anchor against — the engine\n * opts NO resource in, deliberately, and an application's own resource types live outside this\n * repository. Anchoring a minimal sample beside the contract keeps the skill's worked example\n * type-checked and in step with the type, rather than drifting as prose in markdown.\n */\n\nimport type { OrganizationUnitNarrowingDeclaration } from './organization-unit-narrowing.shared';\n\n/**\n * @wildo_source:part:start example.authorization.unit-narrowing.declaration facet:kind:usage-example facet:audience:app-developer\n *\n * Declaring two of an application's own resources unit-narrowable. This map is passed to application\n * startup as `organizationUnitNarrowing`.\n *\n * Each value names the field on THAT resource holding the owning organization unit's id. The field\n * must exist on the resource's schema: it becomes a query predicate on every read and a check on\n * every write, so a misspelled name is an access-control defect rather than a typo.\n *\n * Effect: a member whose only qualifying role is inside a unit is admitted for these resources and\n * confined to that unit's rows (plus its descendants, where the unit inherits downward). A member\n * whose organization-wide role already satisfies the operation is not narrowed at all — so declaring\n * this can widen who can reach a resource, never shrink what someone could already see.\n */\nexport const exampleOrganizationUnitNarrowing: Readonly<Record<string, OrganizationUnitNarrowingDeclaration>> = {\n  projects: { unitFieldName: 'organizationUnitId' },\n  supportTickets: { unitFieldName: 'owningUnitId' },\n};\n/** @wildo_source:part:end example.authorization.unit-narrowing.declaration */\n"]}

package/dist/esm/organizations/organization-unit-narrowing.shared.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Organization-unit narrowing — the opt-in registry and its hard containment rule.
+ *
+ * Unit grants are ADDITIVE (plan decision D-C3b): they widen a principal's reach, never shrink it.
+ * A caller whose organization-wide grant already satisfies an operation is not narrowed at all; a
+ * caller who would otherwise be denied gains access to the rows of the units they hold.
+ *
+ * A resource participates ONLY by opting in here. Narrowing is never implicit: inferring it from the
+ * presence of an `organizationUnitId` field would silently change the result set of every existing
+ * LIST the moment such a field was added.
+ */
+import { CoreResourceType } from '../resources/resources.shared.core.definitions';
+/**
+ * @wildo_source:part:start saas.models.organization-unit-narrowing-declaration facet:layer:shared facet:family:authorization
+ *
+ * How one resource is narrowed: the field carrying the unit a row belongs to.
+ *
+ * Import from `@wildo-ai/saas-models`. Declare narrowing by passing an
+ * `organizationUnitNarrowing` map to application startup, keyed by resource type:
+ *
+ * ```ts
+ * organizationUnitNarrowing: {
+ *   [MyResourceType.PROJECTS]: { unitFieldName: 'organizationUnitId' },
+ * }
+ * ```
+ *
+ * `unitFieldName` must name a real field on the resource's main schema that stores the owning
+ * `ORGANIZATION_UNITS` id — it becomes a query predicate on every read and a write-time check on
+ * every create/update, so a misspelled field is an authorization defect, not a typo.
+ *
+ * Opting in is ADDITIVE: a caller whose organization-wide role already satisfies the operation is
+ * never narrowed and keeps seeing the whole tenant, while a caller who would otherwise be denied
+ * gains access to the rows of the units they hold. Opting a resource in therefore cannot shrink any
+ * existing result set.
+ *
+ * Deliberately an object rather than a bare boolean so per-operation narrowing can be added later as
+ * an optional property (D-C5) without migrating any existing declaration — Dynamics carries depth
+ * per privilege, and Wildo already declares roles per operation variant, so that is the likely next
+ * shape. Resource-level is a strict subset of it.
+ */
+export type OrganizationUnitNarrowingDeclaration = {
+    /** The field on the resource holding the owning `ORGANIZATION_UNITS` id. */
+    readonly unitFieldName: string;
+};
+/** @wildo_source:part:end saas.models.organization-unit-narrowing-declaration */
+/**
+ * Resources that may NEVER be unit-narrowable — the authorization plane (plan decision D-C4).
+ *
+ * ## The loop this closes
+ *
+ * A resource that ISSUES authority must not be governed by the authority it issues. Were
+ * `ORGANIZATION_UNIT_MEMBERS` narrowable:
+ *
+ *   1. a principal who is organization-wide `ORG_MEMBER` but `ORG_ADMIN` of ONE unit
+ *   2. satisfies the `ORG_ADMIN` gate on the grant surface via that unit grant,
+ *   3. grants themselves `ORG_ADMIN` in every other unit,
+ *   4. and the union of all units is organization-wide admin — assembled from a single unit grant.
+ *
+ * Step 3 is blocked today only because the role ceiling derives from organization-wide grants. That
+ * is one refactor away from being undone (see the `D-C4 LOCK` regression test), so the containment
+ * is also structural: a unit grant can never reach these resources at all.
+ *
+ * Every major suite enforces the same separation — SAP puts user↔role assignment behind dedicated
+ * authorization objects, Azure puts role assignment outside the data plane behind
+ * `Microsoft.Authorization/roleAssignments/write`, and Dynamics forbids assigning a role you do not
+ * hold.
+ *
+ * `ORGANIZATION_MEMBERS` is listed for the same reason one level up: it carries the organization-wide
+ * `roles` array that produces `initiatorRoles`. The roles-bearing machine credentials are listed
+ * because the roles written at CREATE become the authority of every token minted from them.
+ *
+ * ## `ORGANIZATIONS` is listed for a SECOND, distinct reason — scope inversion
+ *
+ * The rule above is "a resource that ISSUES authority may not be governed by the authority it
+ * issues". `ORGANIZATIONS` is barred by its sibling: **a resource that DEFINES a scope may not be
+ * governed by a narrowing INSIDE that scope.** A unit is owned BY an organization, so letting the
+ * owned thing gate access to its owner inverts the containment.
+ *
+ * That is not abstract. The tenant lifecycle verbs live on this resource, and
+ * `request_deletion` / `suspend` are `ORG_ADMIN`-gated. Were `ORGANIZATIONS` narrowable, a principal
+ * who is organization-wide `ORG_MEMBER` but `ORG_ADMIN` of ONE unit would satisfy that gate through
+ * the unit grant — and one division's administrator could mark the ENTIRE tenant for deletion, or
+ * halt it. The blast radius is the whole organization, reached from a grant that was supposed to
+ * confine them to a subtree of it.
+ *
+ * It is also meaningless independently of the hazard: an organization is not located inside one of
+ * its own units, so there is no honest `unitFieldName` to declare. Listing it turns a declaration
+ * that could never be correct into a boot failure instead of a silent authorization hole.
+ */
+/** @wildo_source:part:start saas.models.organization-unit-narrowing-containment facet:layer:shared facet:family:authorization */
+export declare const ORGANIZATION_UNIT_NARROWING_FORBIDDEN_RESOURCES: readonly CoreResourceType[];
+/** @wildo_source:part:end saas.models.organization-unit-narrowing-containment */
+/**
+ * The engine's opted-in resources.
+ *
+ * EMPTY BY DESIGN. No engine resource carries a unit FK yet, and opting one in is a deliberate
+ * per-resource decision, not a default. The mechanism ships ahead of its first consumer so that the
+ * containment rule is enforced from the start rather than retrofitted after a resource has already
+ * been narrowed incorrectly.
+ */
+export declare const ENGINE_ORGANIZATION_UNIT_NARROWING: Readonly<Partial<Record<CoreResourceType, OrganizationUnitNarrowingDeclaration>>>;
+/**
+ * Merge the engine's opt-ins with an application's into the map that GOVERNS RUNTIME.
+ *
+ * The engine ships none today, so in practice this is the application's own map — but the merge
+ * exists rather than the application map being used directly, because the containment validation and
+ * every runtime lookup must see ONE map. A second, unmerged source is how a resource ends up narrowed
+ * on the read path and not on the write path.
+ *
+ * An application declaration for a resource the engine also declares REPLACES it: the application
+ * owns the field name on its own schema. Nothing here validates the result — the caller passes the
+ * merged map to {@link collectOrganizationUnitNarrowingViolations} and fails closed at boot, so that
+ * an application cannot narrow the authorization plane merely by declaring it later than the engine.
+ */
+export declare function mergeOrganizationUnitNarrowingDeclarations(engineNarrowing: Readonly<Partial<Record<string, OrganizationUnitNarrowingDeclaration>>>, applicationNarrowing: Readonly<Partial<Record<string, OrganizationUnitNarrowingDeclaration>>> | undefined): Readonly<Partial<Record<string, OrganizationUnitNarrowingDeclaration>>>;
+/** A declaration that violates the D-C4 containment rule. */
+export type OrganizationUnitNarrowingViolation = {
+    readonly resourceType: string;
+    readonly reason: 'authorization_plane_resource_cannot_be_unit_narrowable' | 'missing_unit_field_name';
+};
+/**
+ * Validate a narrowing registry against the containment rule.
+ *
+ * Returns violations rather than throwing so the caller owns the failure mode — the engine boot path
+ * turns these into a startup error (fail closed: a misdeclared narrowing is a silent authorization
+ * hole, so the application must not start), while tooling can report them without dying.
+ */
+export declare function collectOrganizationUnitNarrowingViolations(narrowingRegistry: Readonly<Partial<Record<string, OrganizationUnitNarrowingDeclaration>>>): OrganizationUnitNarrowingViolation[];
+/**
+ * Is this resource narrowed by organization unit?
+ *
+ * The single question every consumer asks. Reading the registry directly is how a call site ends up
+ * disagreeing with the containment rule — the forbidden set is re-checked here so a registry that
+ * was assembled without validation still cannot narrow the authorization plane.
+ */
+export declare function resolveOrganizationUnitNarrowing(narrowingRegistry: Readonly<Partial<Record<string, OrganizationUnitNarrowingDeclaration>>>, resourceType: string): OrganizationUnitNarrowingDeclaration | undefined;
+//# sourceMappingURL=organization-unit-narrowing.shared.d.ts.map

package/dist/esm/organizations/organization-unit-narrowing.shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"organization-unit-narrowing.shared.d.ts","sourceRoot":"","sources":["../../../../src/organizations/organization-unit-narrowing.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,gDAAgD,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,MAAM,oCAAoC,GAAG;IACjD,4EAA4E;IAC5E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,CAAC;AACF,iFAAiF;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,iIAAiI;AACjI,eAAO,MAAM,+CAA+C,EAAE,SAAS,gBAAgB,EAStF,CAAC;AACF,iFAAiF;AAEjF;;;;;;;GAOG;AACH,eAAO,MAAM,kCAAkC,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,oCAAoC,CAAC,CAAC,CAAM,CAAC;AAExI;;;;;;;;;;;;GAYG;AACH,wBAAgB,0CAA0C,CACxD,eAAe,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,oCAAoC,CAAC,CAAC,CAAC,EACxF,oBAAoB,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,oCAAoC,CAAC,CAAC,CAAC,GAAG,SAAS,GACxG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,oCAAoC,CAAC,CAAC,CAAC,CAEzE;AAED,6DAA6D;AAC7D,MAAM,MAAM,kCAAkC,GAAG;IAC/C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,wDAAwD,GAAG,yBAAyB,CAAC;CACvG,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,0CAA0C,CACxD,iBAAiB,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,oCAAoC,CAAC,CAAC,CAAC,GACzF,kCAAkC,EAAE,CAgBtC;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAC9C,iBAAiB,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,oCAAoC,CAAC,CAAC,CAAC,EAC1F,YAAY,EAAE,MAAM,GACnB,oCAAoC,GAAG,SAAS,CAKlD"}