@htilabs/platform-common-models 0.79.0 → 0.80.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,4 +1,4 @@
1
- import { n as PermissionStateValue, d as DefaultBoundStateValue } from '../platform-auth-DJO-r9Pf.cjs';
1
+ import { n as PermissionStateValue, d as DefaultBoundStateValue, o as PlatformToolValue } from '../platform-auth-DJO-r9Pf.cjs';
2
2
  export { D as DEFAULT_BOUND_STATE, a as DEFAULT_BOUND_STATE_DISPLAY, b as DEFAULT_BOUND_STATE_LABELS, c as DEFAULT_BOUND_STATE_VALUES } from '../platform-auth-DJO-r9Pf.cjs';
3
3
  import { d as InformationScopeResolver, l as ScopeReading, w as ScopeSubjectKind } from '../informationScopeResolver-BYiubygD.cjs';
4
4
 
@@ -940,4 +940,176 @@ declare function viewingRowVisible(access: CaseViewingAccess, homeRow: string, s
940
940
  */
941
941
  declare function viewingComponentOpen(access: CaseViewingAccess, homeRow: string, scope: ViewingScopeResolver): boolean;
942
942
 
943
- export { type AuthzFunctionRow, type AuthzRoleOverrides, type AuthzRoleRow, type AuthzStateMap, type AuthzTeamPolicy, type AuthzTier1StateMap, CORE_FUNCTION_DEFAULT_BOUNDS, CORE_FUNCTION_DEFAULT_BOUNDS_SOT_VERSION, CORE_FUNCTION_NOTES, CORE_FUNCTION_NOTES_SOT_VERSION, type CaseViewingAccess, type CoreFunctionNotes, DefaultBoundStateValue, type FunctionDoorInput, type FunctionDoorState, type FunctionLabelLookup, type FunctionRefusal, type GoverningViewingPolicy, type RecordViewingDecision, type RecordViewingReason, type ResolveEffectiveFunctionsInput, type StoredViewingWhitelist, VIEWING_LEVEL_FUNCTIONS, VIEWING_POLICY_SPECIES, VIEWING_POLICY_VOCABULARIES, type ViewingContext, type ViewingLevel, type ViewingPolicyGoverning, type ViewingPolicyNone, type ViewingPolicyQuery, type ViewingPolicyRef, type ViewingPolicyScopeResolver, type ViewingPolicyScopeVocab, type ViewingPolicyUnavailable, type ViewingPolicyUnavailableReason, type ViewingPolicyVocabulary, type ViewingRecord, type ViewingScopeResolver, type ViewingSurface, canonicalRoleCode, caseSurfacesAsStub, caseSurfacesOn, caseViewingAccess, codebookDefaultBound, coreFunctionNotes, explainFunctionRefusal, functionDoor, isCanonEvaluableFunction, recordViewing, resolveEffectiveFunctions, resolveEffectiveViewingLevel, resolveViewingPolicy, selectActingTeamId, teamViewingLevelFromPolicy, unavailableViewingPolicy, viewingComponentOpen, viewingLevelFromFunctions, viewingPolicyVocabulary, viewingRowVisible, viewingWhitelistFromPolicy };
943
+ /**
944
+ * @htilabs/platform-common-models/authz — a seat's app access
945
+ *
946
+ * The ONE answer to "may this person open this app?", shared by Thread's and
947
+ * PAVE's sign-in doors and the platform's app tiles so the three never give
948
+ * different answers. Pure TypeScript: no mongoose, no I/O. The caller reads
949
+ * the seat's teams and the account from its own database and passes them in.
950
+ *
951
+ * ## Canon (Crysta's rulings)
952
+ *
953
+ * - 2026-10-02: "Contract grants apps to the Account, users gain access via
954
+ * teams" (UDD Team Data Object § 2 scenario 1; Account Data Object § 2).
955
+ * - 2026-08-20, Ruling 1: "a user's app access should always be derivable
956
+ * from the union of teams they belong to" (records repo
957
+ * `tools/build_platform_directory.py`, TEAM-APP-ACCESS).
958
+ * - 2026-08-20, Ruling 2: Echo + Trail are granted to "everyone with an
959
+ * account". They are not team-scoped, never appear in a team's apps, and
960
+ * are added at the USER grain only ("an active user of any account gets
961
+ * them"). Same generator; the prototype's user grain adds them to every
962
+ * user (`HTI_appsForUser`, platform-prototype `src/data.js`).
963
+ * - 2026-08-31 (Terry login), TRAIL-ONLY PRE-LAUNCH: a seat whose account is
964
+ * not launched yet reaches Trail only — no casework app and no Echo
965
+ * (`HTI_preLaunchAccountFor`, platform-prototype `src/data.js`).
966
+ * - 2026-10-18: "the team object is where app access is gained".
967
+ * - 2026-10-02 (ORG-ROW-IDENTITY-ONLY-2026-10-08): apps live at the account,
968
+ * the team and the user, never the organization. This function reads no
969
+ * organization or agency apps.
970
+ * - 2026-11-12: HTI loads the account's apps; HTI or account admins put app
971
+ * access on a team, inside that grant; users reach apps through the teams
972
+ * they are on.
973
+ *
974
+ * ## The rule
975
+ *
976
+ * platform side (`teamAllows`):
977
+ * - account not launched (`accountPreLaunch`): Trail only;
978
+ * - Echo, Trail: every seat (Ruling 2), whatever its teams or the grant;
979
+ * - Thread, PAVE, LEADS: some ACTIVE team of the seat carries the app,
980
+ * AND the account grants it when the account grant is known.
981
+ * allowed = auth0Allows OR platform side.
982
+ *
983
+ * ## Where this differs from the prototype's user grain (`HTI_appsForUser`)
984
+ *
985
+ * 1. The Auth0 OR — the TRANSITION. The prototype answers from the teams
986
+ * alone. Production teams are not yet trustworthy (on 2026-10-08 all 64
987
+ * platform-prod teams read `apps: ["PAVE"]`, platform
988
+ * `docs/TEAM_APPS_FIELD.md`), so on day one the answer is ADDITIVE: the
989
+ * app's existing Auth0 decision still lets a person in and the teams can
990
+ * only add access. `via` names which side answered, so the apps can
991
+ * report every seat where the two disagree. When Crysta says the Auth0
992
+ * role stops counting, callers pass `auth0Allows: false` (or this OR is
993
+ * removed). The OR also reaches the pre-launch rule: during the
994
+ * transition an Auth0 yes admits a seat of an account that is not
995
+ * launched yet, where the prototype allows Trail only.
996
+ * 2. An inactive team grants nothing (Crysta 2026-11-12). The prototype's
997
+ * user grain counts every team on the seat; it is being updated to match
998
+ * (platform-prototype `fix/k08c-inactive-team-no-apps`).
999
+ * 3. The account ceiling (Crysta 2026-11-12: teams are set inside the apps
1000
+ * HTI granted the account). The prototype's user grain applies none; with
1001
+ * the grant unknown this function applies none either.
1002
+ *
1003
+ * ## What stays with the caller
1004
+ *
1005
+ * - Which seats are asked about: active seats only. Ruling 2 gives Echo and
1006
+ * Trail to "an active user of any account"; a deactivated seat is refused
1007
+ * before this function is called.
1008
+ * - The Auth0 decision, as a boolean. Which `allowed_apps` values count is
1009
+ * per app and per tier (Thread `config/runtime/api.yaml` THREAD_APP_KEYS:
1010
+ * `thread,thread_test` on dev, `thread,thread_train` on train; PAVE
1011
+ * `apps/api/src/plugins/auth.ts` `appAccessKeys`), so it is not decided
1012
+ * here.
1013
+ * - Which teams are ACTIVE. Stored team status differs by app (Thread's
1014
+ * numeric `status`, the registry's `active` boolean); the caller sets
1015
+ * `active: false` on a retired team. `active` absent or `null` counts as
1016
+ * active.
1017
+ * - The account grant: the account's `apps_subscribed`, "Apps the contract
1018
+ * grants" (UDD Account Data Object; hti-features Account.v1; records
1019
+ * `HTI_ACCOUNT_DIRECTORY.csv`), the list HTI sets. Read it with
1020
+ * {@link accountAppGrant}. Never pass a list derived from the teams, and
1021
+ * never the legacy `accounts.apps` the PAVE sync writes; pass `null`
1022
+ * ("not known") instead. (`apps_declared` was a 2026-10-18 records-
1023
+ * generator artifact, now retired; it is not read.)
1024
+ * - Whether the account is launched. The caller sets `accountPreLaunch` when
1025
+ * the account's `member_status` is `prospective` or `onboarding`.
1026
+ *
1027
+ * ## Reading stored app lists
1028
+ *
1029
+ * A team's or account's apps are read as a list (a bare string counts as a
1030
+ * one-item list), each value trimmed and matched case-insensitively against
1031
+ * the five platform apps: production stores `"PAVE"` (PLATFORM_TOOL codes on
1032
+ * `teams.apps`), canon stores `"pave"` (`apps_used`). Values that name no
1033
+ * platform app (`"PLATFORM"`, `"thread_test"`, `""`), and a stored value that
1034
+ * is neither a list nor a string, are dropped and listed in `unrecognized`; a
1035
+ * tier-suffixed Auth0 role name is never an app here.
1036
+ */
1037
+
1038
+ /** One of the seat's teams, as the caller read it. */
1039
+ interface SeatAppAccessTeam {
1040
+ /**
1041
+ * The apps the team carries: production `teams.apps` (`["PAVE"]`) or
1042
+ * canon's `apps_used` (`["pave"]`). Any case; a bare string is one app.
1043
+ */
1044
+ readonly apps?: unknown;
1045
+ /** `false` for a retired or inactive team, which grants nothing. Absent or `null` counts as active. */
1046
+ readonly active?: boolean | null;
1047
+ }
1048
+ interface SeatAppAccessInput {
1049
+ /** The app being asked about: `"THREAD"`, `"thread"`, `"Thread"` all mean Thread. */
1050
+ readonly app: unknown;
1051
+ /** The app's own Auth0 decision (`allowed_apps` against its accepted keys for this tier). */
1052
+ readonly auth0Allows: boolean;
1053
+ /** The seat's teams. Absent, empty or not a list: the seat is on no team. */
1054
+ readonly teams?: readonly (SeatAppAccessTeam | null | undefined)[] | null;
1055
+ /**
1056
+ * The apps HTI granted the account — its `apps_subscribed`, read with
1057
+ * {@link accountAppGrant}. The ceiling a team cannot
1058
+ * exceed. `null` / `undefined`: not known, so no ceiling applies. A list,
1059
+ * even empty, is a known grant. A value that is neither a list nor a string
1060
+ * is read as a known grant of nothing and reported in `unrecognized`. Echo
1061
+ * and Trail are never limited by it (Ruling 2).
1062
+ */
1063
+ readonly accountGrant?: unknown;
1064
+ /** True when the seat's account is not launched yet (`member_status` prospective / onboarding): Trail only. */
1065
+ readonly accountPreLaunch?: boolean | null;
1066
+ }
1067
+ /** Which side let the person in: the app's Auth0 decision, the platform side (teams and account), both, or neither. */
1068
+ type SeatAppAccessVia = "auth0" | "teams" | "both" | "none";
1069
+ interface SeatAppAccessResult {
1070
+ /** May the seat open the app. */
1071
+ readonly allowed: boolean;
1072
+ /** Which side answered yes. `teams` means the platform side: the seat's teams, its account, Ruling 2. */
1073
+ readonly via: SeatAppAccessVia;
1074
+ /** The app asked about as a PLATFORM_TOOL code (`"THREAD"`), or null when it names no platform app. */
1075
+ readonly app: PlatformToolValue | null;
1076
+ /** The platform side's answer for this app. */
1077
+ readonly teamAllows: boolean;
1078
+ /** Every app the platform side grants the seat (universal apps included), in canonical order. */
1079
+ readonly teamApps: readonly PlatformToolValue[];
1080
+ /** The union of the seat's active teams' apps before the account ceiling, in canonical order. */
1081
+ readonly teamUnion: readonly PlatformToolValue[];
1082
+ /** The account grant as read, in canonical order; null when not known. */
1083
+ readonly accountGrant: readonly PlatformToolValue[] | null;
1084
+ /** Stored app values on the teams or the account that name no platform app, as written. */
1085
+ readonly unrecognized: readonly string[];
1086
+ }
1087
+ /**
1088
+ * The account grant to pass as `accountGrant`: the account's
1089
+ * `apps_subscribed`, "Apps the contract grants" (UDD Account Data Object;
1090
+ * hti-features Account.v1), the list HTI sets. Returns `null` when it is
1091
+ * absent, or for no account. Reads nothing else: never `apps_declared` (a
1092
+ * retired generator artifact) and never the legacy `apps` field.
1093
+ */
1094
+ declare function accountAppGrant(account: {
1095
+ readonly apps_subscribed?: unknown;
1096
+ } | null | undefined): unknown;
1097
+ /**
1098
+ * Every app the platform side grants the seat: Echo and Trail (Ruling 2),
1099
+ * plus the casework apps its active teams carry inside the account grant when
1100
+ * one is known; Trail only before launch. As PLATFORM_TOOL codes, in the
1101
+ * canonical order. The Auth0 role is not part of this answer.
1102
+ */
1103
+ declare function seatTeamApps(input: {
1104
+ readonly teams?: SeatAppAccessInput["teams"];
1105
+ readonly accountGrant?: unknown;
1106
+ readonly accountPreLaunch?: boolean | null;
1107
+ }): PlatformToolValue[];
1108
+ /**
1109
+ * May this seat open this app, and why. See the module comment for the rule.
1110
+ * An app value that names no platform app is never granted by the platform
1111
+ * side; the Auth0 decision still stands for it.
1112
+ */
1113
+ declare function seatAppAccess(input: SeatAppAccessInput): SeatAppAccessResult;
1114
+
1115
+ export { type AuthzFunctionRow, type AuthzRoleOverrides, type AuthzRoleRow, type AuthzStateMap, type AuthzTeamPolicy, type AuthzTier1StateMap, CORE_FUNCTION_DEFAULT_BOUNDS, CORE_FUNCTION_DEFAULT_BOUNDS_SOT_VERSION, CORE_FUNCTION_NOTES, CORE_FUNCTION_NOTES_SOT_VERSION, type CaseViewingAccess, type CoreFunctionNotes, DefaultBoundStateValue, type FunctionDoorInput, type FunctionDoorState, type FunctionLabelLookup, type FunctionRefusal, type GoverningViewingPolicy, type RecordViewingDecision, type RecordViewingReason, type ResolveEffectiveFunctionsInput, type SeatAppAccessInput, type SeatAppAccessResult, type SeatAppAccessTeam, type SeatAppAccessVia, type StoredViewingWhitelist, VIEWING_LEVEL_FUNCTIONS, VIEWING_POLICY_SPECIES, VIEWING_POLICY_VOCABULARIES, type ViewingContext, type ViewingLevel, type ViewingPolicyGoverning, type ViewingPolicyNone, type ViewingPolicyQuery, type ViewingPolicyRef, type ViewingPolicyScopeResolver, type ViewingPolicyScopeVocab, type ViewingPolicyUnavailable, type ViewingPolicyUnavailableReason, type ViewingPolicyVocabulary, type ViewingRecord, type ViewingScopeResolver, type ViewingSurface, accountAppGrant, canonicalRoleCode, caseSurfacesAsStub, caseSurfacesOn, caseViewingAccess, codebookDefaultBound, coreFunctionNotes, explainFunctionRefusal, functionDoor, isCanonEvaluableFunction, recordViewing, resolveEffectiveFunctions, resolveEffectiveViewingLevel, resolveViewingPolicy, seatAppAccess, seatTeamApps, selectActingTeamId, teamViewingLevelFromPolicy, unavailableViewingPolicy, viewingComponentOpen, viewingLevelFromFunctions, viewingPolicyVocabulary, viewingRowVisible, viewingWhitelistFromPolicy };
@@ -1,4 +1,4 @@
1
- import { n as PermissionStateValue, d as DefaultBoundStateValue } from '../platform-auth-DJO-r9Pf.js';
1
+ import { n as PermissionStateValue, d as DefaultBoundStateValue, o as PlatformToolValue } from '../platform-auth-DJO-r9Pf.js';
2
2
  export { D as DEFAULT_BOUND_STATE, a as DEFAULT_BOUND_STATE_DISPLAY, b as DEFAULT_BOUND_STATE_LABELS, c as DEFAULT_BOUND_STATE_VALUES } from '../platform-auth-DJO-r9Pf.js';
3
3
  import { d as InformationScopeResolver, l as ScopeReading, w as ScopeSubjectKind } from '../informationScopeResolver-BYiubygD.js';
4
4
 
@@ -940,4 +940,176 @@ declare function viewingRowVisible(access: CaseViewingAccess, homeRow: string, s
940
940
  */
941
941
  declare function viewingComponentOpen(access: CaseViewingAccess, homeRow: string, scope: ViewingScopeResolver): boolean;
942
942
 
943
- export { type AuthzFunctionRow, type AuthzRoleOverrides, type AuthzRoleRow, type AuthzStateMap, type AuthzTeamPolicy, type AuthzTier1StateMap, CORE_FUNCTION_DEFAULT_BOUNDS, CORE_FUNCTION_DEFAULT_BOUNDS_SOT_VERSION, CORE_FUNCTION_NOTES, CORE_FUNCTION_NOTES_SOT_VERSION, type CaseViewingAccess, type CoreFunctionNotes, DefaultBoundStateValue, type FunctionDoorInput, type FunctionDoorState, type FunctionLabelLookup, type FunctionRefusal, type GoverningViewingPolicy, type RecordViewingDecision, type RecordViewingReason, type ResolveEffectiveFunctionsInput, type StoredViewingWhitelist, VIEWING_LEVEL_FUNCTIONS, VIEWING_POLICY_SPECIES, VIEWING_POLICY_VOCABULARIES, type ViewingContext, type ViewingLevel, type ViewingPolicyGoverning, type ViewingPolicyNone, type ViewingPolicyQuery, type ViewingPolicyRef, type ViewingPolicyScopeResolver, type ViewingPolicyScopeVocab, type ViewingPolicyUnavailable, type ViewingPolicyUnavailableReason, type ViewingPolicyVocabulary, type ViewingRecord, type ViewingScopeResolver, type ViewingSurface, canonicalRoleCode, caseSurfacesAsStub, caseSurfacesOn, caseViewingAccess, codebookDefaultBound, coreFunctionNotes, explainFunctionRefusal, functionDoor, isCanonEvaluableFunction, recordViewing, resolveEffectiveFunctions, resolveEffectiveViewingLevel, resolveViewingPolicy, selectActingTeamId, teamViewingLevelFromPolicy, unavailableViewingPolicy, viewingComponentOpen, viewingLevelFromFunctions, viewingPolicyVocabulary, viewingRowVisible, viewingWhitelistFromPolicy };
943
+ /**
944
+ * @htilabs/platform-common-models/authz — a seat's app access
945
+ *
946
+ * The ONE answer to "may this person open this app?", shared by Thread's and
947
+ * PAVE's sign-in doors and the platform's app tiles so the three never give
948
+ * different answers. Pure TypeScript: no mongoose, no I/O. The caller reads
949
+ * the seat's teams and the account from its own database and passes them in.
950
+ *
951
+ * ## Canon (Crysta's rulings)
952
+ *
953
+ * - 2026-10-02: "Contract grants apps to the Account, users gain access via
954
+ * teams" (UDD Team Data Object § 2 scenario 1; Account Data Object § 2).
955
+ * - 2026-08-20, Ruling 1: "a user's app access should always be derivable
956
+ * from the union of teams they belong to" (records repo
957
+ * `tools/build_platform_directory.py`, TEAM-APP-ACCESS).
958
+ * - 2026-08-20, Ruling 2: Echo + Trail are granted to "everyone with an
959
+ * account". They are not team-scoped, never appear in a team's apps, and
960
+ * are added at the USER grain only ("an active user of any account gets
961
+ * them"). Same generator; the prototype's user grain adds them to every
962
+ * user (`HTI_appsForUser`, platform-prototype `src/data.js`).
963
+ * - 2026-08-31 (Terry login), TRAIL-ONLY PRE-LAUNCH: a seat whose account is
964
+ * not launched yet reaches Trail only — no casework app and no Echo
965
+ * (`HTI_preLaunchAccountFor`, platform-prototype `src/data.js`).
966
+ * - 2026-10-18: "the team object is where app access is gained".
967
+ * - 2026-10-02 (ORG-ROW-IDENTITY-ONLY-2026-10-08): apps live at the account,
968
+ * the team and the user, never the organization. This function reads no
969
+ * organization or agency apps.
970
+ * - 2026-11-12: HTI loads the account's apps; HTI or account admins put app
971
+ * access on a team, inside that grant; users reach apps through the teams
972
+ * they are on.
973
+ *
974
+ * ## The rule
975
+ *
976
+ * platform side (`teamAllows`):
977
+ * - account not launched (`accountPreLaunch`): Trail only;
978
+ * - Echo, Trail: every seat (Ruling 2), whatever its teams or the grant;
979
+ * - Thread, PAVE, LEADS: some ACTIVE team of the seat carries the app,
980
+ * AND the account grants it when the account grant is known.
981
+ * allowed = auth0Allows OR platform side.
982
+ *
983
+ * ## Where this differs from the prototype's user grain (`HTI_appsForUser`)
984
+ *
985
+ * 1. The Auth0 OR — the TRANSITION. The prototype answers from the teams
986
+ * alone. Production teams are not yet trustworthy (on 2026-10-08 all 64
987
+ * platform-prod teams read `apps: ["PAVE"]`, platform
988
+ * `docs/TEAM_APPS_FIELD.md`), so on day one the answer is ADDITIVE: the
989
+ * app's existing Auth0 decision still lets a person in and the teams can
990
+ * only add access. `via` names which side answered, so the apps can
991
+ * report every seat where the two disagree. When Crysta says the Auth0
992
+ * role stops counting, callers pass `auth0Allows: false` (or this OR is
993
+ * removed). The OR also reaches the pre-launch rule: during the
994
+ * transition an Auth0 yes admits a seat of an account that is not
995
+ * launched yet, where the prototype allows Trail only.
996
+ * 2. An inactive team grants nothing (Crysta 2026-11-12). The prototype's
997
+ * user grain counts every team on the seat; it is being updated to match
998
+ * (platform-prototype `fix/k08c-inactive-team-no-apps`).
999
+ * 3. The account ceiling (Crysta 2026-11-12: teams are set inside the apps
1000
+ * HTI granted the account). The prototype's user grain applies none; with
1001
+ * the grant unknown this function applies none either.
1002
+ *
1003
+ * ## What stays with the caller
1004
+ *
1005
+ * - Which seats are asked about: active seats only. Ruling 2 gives Echo and
1006
+ * Trail to "an active user of any account"; a deactivated seat is refused
1007
+ * before this function is called.
1008
+ * - The Auth0 decision, as a boolean. Which `allowed_apps` values count is
1009
+ * per app and per tier (Thread `config/runtime/api.yaml` THREAD_APP_KEYS:
1010
+ * `thread,thread_test` on dev, `thread,thread_train` on train; PAVE
1011
+ * `apps/api/src/plugins/auth.ts` `appAccessKeys`), so it is not decided
1012
+ * here.
1013
+ * - Which teams are ACTIVE. Stored team status differs by app (Thread's
1014
+ * numeric `status`, the registry's `active` boolean); the caller sets
1015
+ * `active: false` on a retired team. `active` absent or `null` counts as
1016
+ * active.
1017
+ * - The account grant: the account's `apps_subscribed`, "Apps the contract
1018
+ * grants" (UDD Account Data Object; hti-features Account.v1; records
1019
+ * `HTI_ACCOUNT_DIRECTORY.csv`), the list HTI sets. Read it with
1020
+ * {@link accountAppGrant}. Never pass a list derived from the teams, and
1021
+ * never the legacy `accounts.apps` the PAVE sync writes; pass `null`
1022
+ * ("not known") instead. (`apps_declared` was a 2026-10-18 records-
1023
+ * generator artifact, now retired; it is not read.)
1024
+ * - Whether the account is launched. The caller sets `accountPreLaunch` when
1025
+ * the account's `member_status` is `prospective` or `onboarding`.
1026
+ *
1027
+ * ## Reading stored app lists
1028
+ *
1029
+ * A team's or account's apps are read as a list (a bare string counts as a
1030
+ * one-item list), each value trimmed and matched case-insensitively against
1031
+ * the five platform apps: production stores `"PAVE"` (PLATFORM_TOOL codes on
1032
+ * `teams.apps`), canon stores `"pave"` (`apps_used`). Values that name no
1033
+ * platform app (`"PLATFORM"`, `"thread_test"`, `""`), and a stored value that
1034
+ * is neither a list nor a string, are dropped and listed in `unrecognized`; a
1035
+ * tier-suffixed Auth0 role name is never an app here.
1036
+ */
1037
+
1038
+ /** One of the seat's teams, as the caller read it. */
1039
+ interface SeatAppAccessTeam {
1040
+ /**
1041
+ * The apps the team carries: production `teams.apps` (`["PAVE"]`) or
1042
+ * canon's `apps_used` (`["pave"]`). Any case; a bare string is one app.
1043
+ */
1044
+ readonly apps?: unknown;
1045
+ /** `false` for a retired or inactive team, which grants nothing. Absent or `null` counts as active. */
1046
+ readonly active?: boolean | null;
1047
+ }
1048
+ interface SeatAppAccessInput {
1049
+ /** The app being asked about: `"THREAD"`, `"thread"`, `"Thread"` all mean Thread. */
1050
+ readonly app: unknown;
1051
+ /** The app's own Auth0 decision (`allowed_apps` against its accepted keys for this tier). */
1052
+ readonly auth0Allows: boolean;
1053
+ /** The seat's teams. Absent, empty or not a list: the seat is on no team. */
1054
+ readonly teams?: readonly (SeatAppAccessTeam | null | undefined)[] | null;
1055
+ /**
1056
+ * The apps HTI granted the account — its `apps_subscribed`, read with
1057
+ * {@link accountAppGrant}. The ceiling a team cannot
1058
+ * exceed. `null` / `undefined`: not known, so no ceiling applies. A list,
1059
+ * even empty, is a known grant. A value that is neither a list nor a string
1060
+ * is read as a known grant of nothing and reported in `unrecognized`. Echo
1061
+ * and Trail are never limited by it (Ruling 2).
1062
+ */
1063
+ readonly accountGrant?: unknown;
1064
+ /** True when the seat's account is not launched yet (`member_status` prospective / onboarding): Trail only. */
1065
+ readonly accountPreLaunch?: boolean | null;
1066
+ }
1067
+ /** Which side let the person in: the app's Auth0 decision, the platform side (teams and account), both, or neither. */
1068
+ type SeatAppAccessVia = "auth0" | "teams" | "both" | "none";
1069
+ interface SeatAppAccessResult {
1070
+ /** May the seat open the app. */
1071
+ readonly allowed: boolean;
1072
+ /** Which side answered yes. `teams` means the platform side: the seat's teams, its account, Ruling 2. */
1073
+ readonly via: SeatAppAccessVia;
1074
+ /** The app asked about as a PLATFORM_TOOL code (`"THREAD"`), or null when it names no platform app. */
1075
+ readonly app: PlatformToolValue | null;
1076
+ /** The platform side's answer for this app. */
1077
+ readonly teamAllows: boolean;
1078
+ /** Every app the platform side grants the seat (universal apps included), in canonical order. */
1079
+ readonly teamApps: readonly PlatformToolValue[];
1080
+ /** The union of the seat's active teams' apps before the account ceiling, in canonical order. */
1081
+ readonly teamUnion: readonly PlatformToolValue[];
1082
+ /** The account grant as read, in canonical order; null when not known. */
1083
+ readonly accountGrant: readonly PlatformToolValue[] | null;
1084
+ /** Stored app values on the teams or the account that name no platform app, as written. */
1085
+ readonly unrecognized: readonly string[];
1086
+ }
1087
+ /**
1088
+ * The account grant to pass as `accountGrant`: the account's
1089
+ * `apps_subscribed`, "Apps the contract grants" (UDD Account Data Object;
1090
+ * hti-features Account.v1), the list HTI sets. Returns `null` when it is
1091
+ * absent, or for no account. Reads nothing else: never `apps_declared` (a
1092
+ * retired generator artifact) and never the legacy `apps` field.
1093
+ */
1094
+ declare function accountAppGrant(account: {
1095
+ readonly apps_subscribed?: unknown;
1096
+ } | null | undefined): unknown;
1097
+ /**
1098
+ * Every app the platform side grants the seat: Echo and Trail (Ruling 2),
1099
+ * plus the casework apps its active teams carry inside the account grant when
1100
+ * one is known; Trail only before launch. As PLATFORM_TOOL codes, in the
1101
+ * canonical order. The Auth0 role is not part of this answer.
1102
+ */
1103
+ declare function seatTeamApps(input: {
1104
+ readonly teams?: SeatAppAccessInput["teams"];
1105
+ readonly accountGrant?: unknown;
1106
+ readonly accountPreLaunch?: boolean | null;
1107
+ }): PlatformToolValue[];
1108
+ /**
1109
+ * May this seat open this app, and why. See the module comment for the rule.
1110
+ * An app value that names no platform app is never granted by the platform
1111
+ * side; the Auth0 decision still stands for it.
1112
+ */
1113
+ declare function seatAppAccess(input: SeatAppAccessInput): SeatAppAccessResult;
1114
+
1115
+ export { type AuthzFunctionRow, type AuthzRoleOverrides, type AuthzRoleRow, type AuthzStateMap, type AuthzTeamPolicy, type AuthzTier1StateMap, CORE_FUNCTION_DEFAULT_BOUNDS, CORE_FUNCTION_DEFAULT_BOUNDS_SOT_VERSION, CORE_FUNCTION_NOTES, CORE_FUNCTION_NOTES_SOT_VERSION, type CaseViewingAccess, type CoreFunctionNotes, DefaultBoundStateValue, type FunctionDoorInput, type FunctionDoorState, type FunctionLabelLookup, type FunctionRefusal, type GoverningViewingPolicy, type RecordViewingDecision, type RecordViewingReason, type ResolveEffectiveFunctionsInput, type SeatAppAccessInput, type SeatAppAccessResult, type SeatAppAccessTeam, type SeatAppAccessVia, type StoredViewingWhitelist, VIEWING_LEVEL_FUNCTIONS, VIEWING_POLICY_SPECIES, VIEWING_POLICY_VOCABULARIES, type ViewingContext, type ViewingLevel, type ViewingPolicyGoverning, type ViewingPolicyNone, type ViewingPolicyQuery, type ViewingPolicyRef, type ViewingPolicyScopeResolver, type ViewingPolicyScopeVocab, type ViewingPolicyUnavailable, type ViewingPolicyUnavailableReason, type ViewingPolicyVocabulary, type ViewingRecord, type ViewingScopeResolver, type ViewingSurface, accountAppGrant, canonicalRoleCode, caseSurfacesAsStub, caseSurfacesOn, caseViewingAccess, codebookDefaultBound, coreFunctionNotes, explainFunctionRefusal, functionDoor, isCanonEvaluableFunction, recordViewing, resolveEffectiveFunctions, resolveEffectiveViewingLevel, resolveViewingPolicy, seatAppAccess, seatTeamApps, selectActingTeamId, teamViewingLevelFromPolicy, unavailableViewingPolicy, viewingComponentOpen, viewingLevelFromFunctions, viewingPolicyVocabulary, viewingRowVisible, viewingWhitelistFromPolicy };
@@ -1146,8 +1146,8 @@ function governingRowOf(rows) {
1146
1146
  if (rows.length === 1 && only !== void 0) return { row: only };
1147
1147
  const family = idText(rows[0]?.familyId);
1148
1148
  const versions = rows.map((r) => positiveIntOrNull(r.version));
1149
- const ordered = family !== null && rows.every((r) => idText(r.familyId) === family) && versions.every((v) => typeof v === "number") && new Set(versions).size === versions.length;
1150
- if (!ordered) {
1149
+ const ordered2 = family !== null && rows.every((r) => idText(r.familyId) === family) && versions.every((v) => typeof v === "number") && new Set(versions).size === versions.length;
1150
+ if (!ordered2) {
1151
1151
  return unavailableViewingPolicy("ambiguous_rows", policyIdOf(rows[0] ?? {}));
1152
1152
  }
1153
1153
  let best = rows[0];
@@ -1404,6 +1404,152 @@ function viewingComponentOpen(access, homeRow, scope) {
1404
1404
  if (row.status === "retired") return false;
1405
1405
  return scope.isCovered(access.visibleScope, homeRow);
1406
1406
  }
1407
+
1408
+ // src/generated/platformApps.ts
1409
+ var PLATFORM_APP_CATALOG = [
1410
+ {
1411
+ "id": "trail",
1412
+ "name": "Trail",
1413
+ "tag": "Certified Access & Training",
1414
+ "universal": true
1415
+ },
1416
+ {
1417
+ "id": "thread",
1418
+ "name": "Thread",
1419
+ "tag": "First Contact Routing",
1420
+ "universal": false
1421
+ },
1422
+ {
1423
+ "id": "pave",
1424
+ "name": "PAVE",
1425
+ "tag": "Survivor-Centered Navigation",
1426
+ "universal": false
1427
+ },
1428
+ {
1429
+ "id": "leads",
1430
+ "name": "LEADS",
1431
+ "tag": "Intelligence-Driven Investigation",
1432
+ "universal": false
1433
+ },
1434
+ {
1435
+ "id": "echo",
1436
+ "name": "Echo",
1437
+ "tag": "Outcomes, Learning, & Impact",
1438
+ "universal": true
1439
+ }
1440
+ ];
1441
+
1442
+ // src/constants/platform-apps.ts
1443
+ var PLATFORM_APP_IDS = ["trail", "thread", "pave", "leads", "echo"];
1444
+ if (PLATFORM_APP_CATALOG.length !== PLATFORM_APP_IDS.length || PLATFORM_APP_CATALOG.some((a, i) => a.id !== PLATFORM_APP_IDS[i])) {
1445
+ throw new Error(
1446
+ `platformApps.ts: canon lists [${PLATFORM_APP_CATALOG.map((a) => a.id).join(", ")}], PLATFORM_APP_IDS [${PLATFORM_APP_IDS.join(", ")}]`
1447
+ );
1448
+ }
1449
+ var PLATFORM_APPS = PLATFORM_APP_CATALOG.map((a) => ({
1450
+ id: a.id,
1451
+ name: a.name,
1452
+ tagline: a.tag,
1453
+ universal: a.universal
1454
+ }));
1455
+ var PLATFORM_APP_NAMES = Object.fromEntries(
1456
+ PLATFORM_APPS.map((a) => [a.id, a.name])
1457
+ );
1458
+ var CASEWORK_APP_IDS = PLATFORM_APPS.filter(
1459
+ (a) => !a.universal
1460
+ ).map((a) => a.id);
1461
+ var UNIVERSAL_APP_IDS = PLATFORM_APPS.filter(
1462
+ (a) => a.universal
1463
+ ).map((a) => a.id);
1464
+ var BY_ID = new Map(PLATFORM_APPS.map((a) => [a.id, a]));
1465
+ function platformAppById(id) {
1466
+ return typeof id === "string" ? BY_ID.get(id.trim().toLowerCase()) ?? null : null;
1467
+ }
1468
+
1469
+ // src/authz/seatAppAccess.ts
1470
+ var UNIVERSAL = new Set(UNIVERSAL_APP_IDS);
1471
+ var TRAIL = "trail";
1472
+ function toolCode(id) {
1473
+ return id.toUpperCase();
1474
+ }
1475
+ function asWritten(v) {
1476
+ if (typeof v === "string") return v;
1477
+ try {
1478
+ const json = JSON.stringify(v);
1479
+ return json === void 0 ? String(v) : json;
1480
+ } catch {
1481
+ return String(v);
1482
+ }
1483
+ }
1484
+ function listOf(value, unrecognized) {
1485
+ if (value === null || value === void 0) return [];
1486
+ if (typeof value === "string") return [value];
1487
+ if (Array.isArray(value)) return value;
1488
+ unrecognized.push(asWritten(value));
1489
+ return [];
1490
+ }
1491
+ function readApps(value, unrecognized) {
1492
+ const out = /* @__PURE__ */ new Set();
1493
+ for (const v of listOf(value, unrecognized)) {
1494
+ const app = platformAppById(v);
1495
+ if (app) out.add(app.id);
1496
+ else unrecognized.push(asWritten(v));
1497
+ }
1498
+ return out;
1499
+ }
1500
+ function ordered(ids) {
1501
+ return PLATFORM_APP_IDS.filter((id) => ids.has(id)).map(toolCode);
1502
+ }
1503
+ function readGrant(value, unrecognized) {
1504
+ if (value === null || value === void 0) return null;
1505
+ return readApps(value, unrecognized);
1506
+ }
1507
+ function accountAppGrant(account) {
1508
+ if (!account || typeof account !== "object") return null;
1509
+ const grant = account.apps_subscribed;
1510
+ return grant === null || grant === void 0 ? null : grant;
1511
+ }
1512
+ function teamSide(teams, accountGrant, accountPreLaunch) {
1513
+ const unrecognized = [];
1514
+ const grant = readGrant(accountGrant, unrecognized);
1515
+ const union = /* @__PURE__ */ new Set();
1516
+ for (const team of Array.isArray(teams) ? teams : []) {
1517
+ if (!team || typeof team !== "object") continue;
1518
+ const t = team;
1519
+ if (t.active === false) continue;
1520
+ for (const id of readApps(t.apps, unrecognized)) union.add(id);
1521
+ }
1522
+ const granted = /* @__PURE__ */ new Set();
1523
+ if (accountPreLaunch === true) {
1524
+ granted.add(TRAIL);
1525
+ return { granted, union, grant, unrecognized };
1526
+ }
1527
+ for (const id of UNIVERSAL) granted.add(id);
1528
+ for (const id of CASEWORK_APP_IDS) {
1529
+ if (union.has(id) && (grant === null || grant.has(id))) granted.add(id);
1530
+ }
1531
+ return { granted, union, grant, unrecognized };
1532
+ }
1533
+ function seatTeamApps(input) {
1534
+ return ordered(teamSide(input.teams, input.accountGrant, input.accountPreLaunch).granted);
1535
+ }
1536
+ function seatAppAccess(input) {
1537
+ const side = teamSide(input.teams, input.accountGrant, input.accountPreLaunch);
1538
+ const app = platformAppById(input.app);
1539
+ const teamAllows = app !== null && side.granted.has(app.id);
1540
+ const auth0Allows = input.auth0Allows === true;
1541
+ const via = auth0Allows && teamAllows ? "both" : auth0Allows ? "auth0" : teamAllows ? "teams" : "none";
1542
+ return {
1543
+ allowed: auth0Allows || teamAllows,
1544
+ via,
1545
+ app: app ? toolCode(app.id) : null,
1546
+ teamAllows,
1547
+ teamApps: ordered(side.granted),
1548
+ teamUnion: ordered(side.union),
1549
+ accountGrant: side.grant ? ordered(side.grant) : null,
1550
+ unrecognized: side.unrecognized
1551
+ };
1552
+ }
1407
1553
  export {
1408
1554
  CORE_FUNCTION_DEFAULT_BOUNDS,
1409
1555
  CORE_FUNCTION_DEFAULT_BOUNDS_SOT_VERSION,
@@ -1416,6 +1562,7 @@ export {
1416
1562
  VIEWING_LEVEL_FUNCTIONS,
1417
1563
  VIEWING_POLICY_SPECIES,
1418
1564
  VIEWING_POLICY_VOCABULARIES,
1565
+ accountAppGrant,
1419
1566
  canonicalRoleCode,
1420
1567
  caseSurfacesAsStub,
1421
1568
  caseSurfacesOn,
@@ -1429,6 +1576,8 @@ export {
1429
1576
  resolveEffectiveFunctions,
1430
1577
  resolveEffectiveViewingLevel,
1431
1578
  resolveViewingPolicy,
1579
+ seatAppAccess,
1580
+ seatTeamApps,
1432
1581
  selectActingTeamId,
1433
1582
  teamViewingLevelFromPolicy,
1434
1583
  unavailableViewingPolicy,