@htilabs/platform-common-models 0.54.0 → 0.55.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.
Files changed (33) hide show
  1. package/README.md +48 -0
  2. package/dist/authz/index.cjs.map +1 -1
  3. package/dist/authz/index.d.cts +10 -8
  4. package/dist/authz/index.d.ts +10 -8
  5. package/dist/authz/index.js.map +1 -1
  6. package/dist/{index-XWSYon40.d.cts → index-Bj-s0nZy.d.cts} +1 -1
  7. package/dist/{index-Bh1zO_Vu.d.ts → index-DvAypMJV.d.ts} +1 -1
  8. package/dist/index.cjs +152 -2
  9. package/dist/index.cjs.map +1 -1
  10. package/dist/index.d.cts +3 -3
  11. package/dist/index.d.ts +3 -3
  12. package/dist/index.js +145 -2
  13. package/dist/index.js.map +1 -1
  14. package/dist/models/index.d.cts +2 -2
  15. package/dist/models/index.d.ts +2 -2
  16. package/dist/schemas/index.d.cts +25 -25
  17. package/dist/schemas/index.d.ts +25 -25
  18. package/dist/sharing-ceiling/index.cjs +152 -2
  19. package/dist/sharing-ceiling/index.cjs.map +1 -1
  20. package/dist/sharing-ceiling/index.d.cts +214 -2
  21. package/dist/sharing-ceiling/index.d.ts +214 -2
  22. package/dist/sharing-ceiling/index.js +145 -2
  23. package/dist/sharing-ceiling/index.js.map +1 -1
  24. package/package.json +1 -1
  25. package/src/__tests__/core-function-default-bounds.test.ts +2 -2
  26. package/src/authz/functionDoor.ts +4 -4
  27. package/src/authz/resolveEffectiveFunctions.ts +6 -4
  28. package/src/sharingCeiling/__tests__/fireShareEvent.test.ts +437 -0
  29. package/src/sharingCeiling/fireShareEvent.ts +352 -0
  30. package/src/sharingCeiling/index.ts +4 -0
  31. package/src/sharingCeiling/resolve.ts +31 -5
  32. package/dist/{cvcEntry-D787utvP.d.cts → cvcEntry-BLeRivoF.d.cts} +8 -8
  33. package/dist/{cvcEntry-D787utvP.d.ts → cvcEntry-BLeRivoF.d.ts} +8 -8
@@ -497,6 +497,16 @@ type SharePolicyAssignment = {
497
497
  readonly teamRowId: string;
498
498
  readonly teamId?: string;
499
499
  readonly partnerId?: string | null;
500
+ /**
501
+ * The other end of the row, as the Admin Hub stores it on the link
502
+ * (data.js `policyRecord`): `{ type: "team", id }` names a receiving
503
+ * team — one of the account's own (no `partnerId`) or the partner's.
504
+ * The ladder does not read it (the row decides); `fireShareEvent` does.
505
+ */
506
+ readonly with?: {
507
+ readonly type?: string;
508
+ readonly id?: string;
509
+ } | null;
500
510
  };
501
511
  /** A policy document as the Admin Hub stores it (data.js `policyRecord` L53540ff). */
502
512
  interface SharePolicyDoc {
@@ -523,9 +533,19 @@ interface SharePolicyDoc {
523
533
  readonly edited?: boolean;
524
534
  /** `false` = retired: never governs. */
525
535
  readonly active?: boolean;
526
- /** `answers: "received"` (K13-9b): a share-back policy never governs a share you start. */
536
+ /**
537
+ * `answers: "received"` (K13-9b): a share-back policy never governs a share you start.
538
+ * `on` (K13-9a): the CVC-285 event names a LISTENER fires on — read by
539
+ * `fireShareEvent`, never by the ladder.
540
+ */
527
541
  readonly trigger?: {
528
542
  readonly answers?: string;
543
+ readonly on?: readonly string[];
544
+ } | null;
545
+ /** CVC-85 cadences the policy grants; `ongoing` + a trigger makes it a listener (K13-9a). */
546
+ readonly cadences?: {
547
+ readonly ongoing?: boolean;
548
+ readonly automatic?: boolean;
529
549
  } | null;
530
550
  }
531
551
  /** The Platform default for one purpose, as the four states (data.js `platformStarterScope` L53719ff). */
@@ -782,4 +802,196 @@ declare function shareRowCeiling(resolution: Pick<ShareResolution, "allowed" | "
782
802
  */
783
803
  declare function resolveShare(input: ShareResolveInput): ShareResolution;
784
804
 
785
- export { type AccountSharePurposePolicy, type EffectiveSharingCeiling, type EffectiveSharingCeilingInputs, HTI_SHARE_PLATFORM_PURPOSE_ENABLED, HTI_SHARE_PLATFORM_REQUIRED_BY_PURPOSE, HTI_SHARE_PLATFORM_STARTER, HTI_SHARE_PLATFORM_STARTER_SOURCE, INFORMATION_SCOPE_FIELD_HOME_ROWS, SHARE_LEVEL_LABEL, SHARE_PLATFORM_STATE_LABEL, SHARE_POSTURE_RANK, SHARE_REPORTING_PURPOSES, SHARING_CEILING_DEFAULT_ROW_KEY, SHARING_CEILING_EXTERNAL_ROW_KEY, SHARING_CEILING_SCOPE_VERSION, type ShareAttachmentIndex, type ShareCategoryEntry, type ShareDefaultScopeOptions, type ShareLevel, type ShareNamedPolicy, type SharePlatformDefault, type SharePlatformState, type SharePolicyAssignment, type SharePolicyDoc, type SharePosture, type ShareRecipient, type ShareResolution, type ShareResolveInput, type ShareTeamRowLike, type SharingCeilingAllowed, type SharingCeilingCellLike, type SharingCeilingRung, type SharingCeilingScope, type SharingPlatformStarter, type SharingPurposeLists, type SharingScopeCeiling, type SharingScopeEdits, accountSharePurposePolicy, attachmentIndexFromPolicies, ceilingCoverage, derivePlatformDefault, effectiveCeiling, hasOwnScopeContent, intersectSharingCeilingLists, isCeilingCoverageRow, isPermittedByCeiling, isSharingPurposeDisabled, liveCategories, maskSelectionToCeiling, matchTeamRow, platformDefaultFor, resolveShare, rowsExpandedByCeiling, rowsOutsideCeiling, rowsOverCeiling, scopeListCovers, scopeListStrictlyCovers, scopeRowWithinCeiling, shareDefaultScopeFor, shareRowCeiling, sharingCeilingCellList, sharingCeilingRowKey, sharingScopeEditsFromCells, systemCategoryOf };
805
+ /**
806
+ * EVENT-DRIVEN SHARING — which listeners an event fires (Kickoff 13 build
807
+ * item 9a; Crysta 2026-10-19 14:26 "enabling vs firing"; home ruled
808
+ * 2026-11-01: platform-common exports `ShareEvent` + `fireShareEvent(policies,
809
+ * event)` as a pure function, and each app calls it after commit at session
810
+ * submit and case close).
811
+ *
812
+ * Contract of record: platform-prototype `src/data.js` — `TRIGGER_EVENTS`,
813
+ * `policyIsListener`, `listenersFor`, `fireShareEvent` (K13-9a
814
+ * EVENT-LISTENER 2026-10-22).
815
+ *
816
+ * ENABLING is a Policy with the `ongoing` cadence and a trigger, linked team
817
+ * → team or team → partner: standing permission, authored by the Member
818
+ * Admin. FIRING writes an ORDINARY share — the policy's purpose and version
819
+ * on it — down the normal notify → review → claim path; only the author
820
+ * differs.
821
+ *
822
+ * This module answers ONE question and decides nothing else: given the
823
+ * sending account's policy documents and an event raised by a team, which
824
+ * listeners fire, and to whom. Everything a manual share of that purpose
825
+ * would be held to still applies and stays where it lives — the app sends
826
+ * each answer through its own send door: `resolveShare` for what may leave
827
+ * (and the policy's posture — `approval` waits, `blocked` holds), the release
828
+ * for a partner (one that covers the `ongoing` cadence), the account's
829
+ * catalog, the floor. A fired share is never a way around a rule.
830
+ *
831
+ * THE CALLER'S TWO DUTIES. (1) A link is read from the policy document's own
832
+ * `assignments`; pass the account's team rows as `options.teamRows` (or check
833
+ * `teamRowId` against your row store before sending) so a link whose row was
834
+ * deleted, or no longer says what the document says, fires nothing. (2) An
835
+ * event that can happen more than once on one subject (a note, a service, a
836
+ * status change) needs its own `ref`, or the second is taken for the first.
837
+ *
838
+ * Pure: no I/O, no clock, no randomness. The same input gives the same
839
+ * output, so a caller can run it twice and compare `key`s to fire each
840
+ * listener ONCE per event per subject (pass the keys already written as
841
+ * `alreadyFired`).
842
+ */
843
+
844
+ /**
845
+ * The events a listener may name. A trigger is a flag over EXISTING codes —
846
+ * the CVC-285 event names the platform already emits — and mints no new CVC
847
+ * (open point 5's default). The subset a case or a share can raise, in the
848
+ * prototype's order and words.
849
+ */
850
+ declare const SHARE_TRIGGER_EVENTS: readonly [{
851
+ readonly code: "sessionSubmitted";
852
+ readonly label: "Session submitted";
853
+ readonly group: "case";
854
+ }, {
855
+ readonly code: "caseOpened";
856
+ readonly label: "Case opened";
857
+ readonly group: "case";
858
+ }, {
859
+ readonly code: "caseStatusChanged";
860
+ readonly label: "Case status changed";
861
+ readonly group: "case";
862
+ }, {
863
+ readonly code: "caseCloseRuled";
864
+ readonly label: "Case closed";
865
+ readonly group: "case";
866
+ }, {
867
+ readonly code: "determinationIssued";
868
+ readonly label: "Determination issued";
869
+ readonly group: "case";
870
+ }, {
871
+ readonly code: "serviceLogged";
872
+ readonly label: "Service logged";
873
+ readonly group: "case";
874
+ }, {
875
+ readonly code: "noteAdded";
876
+ readonly label: "Note added";
877
+ readonly group: "case";
878
+ }, {
879
+ readonly code: "shareClaimed";
880
+ readonly label: "Share you sent claimed";
881
+ readonly group: "share";
882
+ }, {
883
+ readonly code: "referralClaimed";
884
+ readonly label: "Referral you sent claimed";
885
+ readonly group: "share";
886
+ }, {
887
+ readonly code: "shareAcknowledged";
888
+ readonly label: "Share you sent acknowledged";
889
+ readonly group: "share";
890
+ }];
891
+ type ShareTriggerEventCode = (typeof SHARE_TRIGGER_EVENTS)[number]["code"];
892
+ /** The two events the apps raise today (session submit · case close). */
893
+ declare const SHARE_EVENT: Readonly<{
894
+ readonly SESSION_SUBMITTED: "sessionSubmitted";
895
+ readonly CASE_CLOSED: "caseCloseRuled";
896
+ }>;
897
+ /** The words a person reads for a trigger code (the code itself when unknown). */
898
+ declare function shareTriggerLabel(code: string): string;
899
+ /** Something that happened on a case or a session, raised by the team that did it. */
900
+ interface ShareEvent {
901
+ /** The CVC-285 event name (`SHARE_EVENT`, `SHARE_TRIGGER_EVENTS`). */
902
+ readonly event: string;
903
+ /**
904
+ * The ACTING team — a listener is a link FROM a team, so an event with no
905
+ * team fires nothing.
906
+ */
907
+ readonly teamId: string | null | undefined;
908
+ /** Informational: `policies` must already be the sending account's documents. */
909
+ readonly accountId?: string | null;
910
+ readonly caseId?: string | null;
911
+ readonly sessionId?: string | null;
912
+ /**
913
+ * What the event is about, for the once-only key. Default: the session id
914
+ * for `sessionSubmitted`; for every other event the case id, else the
915
+ * session id; else none (every such event shares one key). Pass it
916
+ * explicitly for an event that can repeat on one case.
917
+ */
918
+ readonly ref?: string | null;
919
+ }
920
+ /** One listener: a policy with the `ongoing` cadence and a trigger, on one team link. */
921
+ interface ShareListener {
922
+ readonly policy: {
923
+ readonly id: string;
924
+ readonly familyId: string;
925
+ readonly name: string;
926
+ readonly version: number;
927
+ };
928
+ readonly purpose: string;
929
+ readonly fromTeamId: string;
930
+ /** The link's row — what `resolveShare` takes as `teamRowId`. */
931
+ readonly teamRowId: string;
932
+ /** Who it sends to, in the resolver's own vocabulary. */
933
+ readonly recipient: Extract<ShareRecipient, {
934
+ kind: "partner";
935
+ } | {
936
+ kind: "sibling_team";
937
+ }>;
938
+ /** A team → partner-team link names the partner's team; else `null`. */
939
+ readonly partnerTeamId: string | null;
940
+ /** The events it listens for. */
941
+ readonly events: readonly string[];
942
+ }
943
+ /** One listener an event raised — the share the app is to write. */
944
+ interface FiredShare extends ShareListener {
945
+ readonly event: string;
946
+ readonly ref: string | null;
947
+ /**
948
+ * Stable for one event × subject × policy × sending team × recipient: the
949
+ * same event on the same case fires each listener ONCE. Opaque — compare
950
+ * it, never parse it.
951
+ */
952
+ readonly key: string;
953
+ }
954
+ /**
955
+ * A policy that listens: live, `ongoing` cadence, at least one trigger event
956
+ * (data.js `policyIsListener`) — and NOT a share-back policy
957
+ * (`trigger.answers === "received"`, K13-9b), which answers a share received
958
+ * and never fires on a case event.
959
+ */
960
+ declare function policyIsShareListener(p: SharePolicyDoc | null | undefined): boolean;
961
+ /**
962
+ * The listeners linked FROM one team (data.js `listenersFor`): each listening
963
+ * policy × each of its team → team / team → partner links whose sending team
964
+ * is `teamId`. A link that names no sending team, a different team, or no
965
+ * target is not a listener for this team. The policy must also be the one
966
+ * that HOLDS the row's cell for its purpose (`attachmentIndexFromPolicies` —
967
+ * two live documents on one cell: the later wins, exactly as the ladder
968
+ * reads it), so the share a listener fires is governed by that same policy.
969
+ * Two links of one policy to the same place are one listener (the first, in
970
+ * document order). `options.event` keeps only the policies listening for
971
+ * that event; `options.teamRows`, when given, drops a link whose row is gone
972
+ * or disagrees with it.
973
+ */
974
+ declare function shareListenersFor(policies: readonly SharePolicyDoc[] | null | undefined, teamId: string | null | undefined, options?: {
975
+ readonly event?: string | null;
976
+ readonly teamRows?: readonly ShareTeamRowLike[] | null;
977
+ }): ShareListener[];
978
+ /** The once-only key of one fired share (see `FiredShare.key`). */
979
+ declare function firedShareKey(event: string, ref: string | null, listener: Pick<ShareListener, "policy" | "fromTeamId" | "recipient" | "partnerTeamId">): string;
980
+ /**
981
+ * FIRING (data.js `fireShareEvent`, the pure half): the listeners linked from
982
+ * the acting team that listen for this event, each as the share to write.
983
+ * Call it AFTER the event's own write commits. `[]` when the event names no
984
+ * team or no event, when nothing listens — and for every listener whose key
985
+ * is in `alreadyFired` (what the app has written for this event before).
986
+ *
987
+ * The app then sends each one as an ordinary share of `purpose` to
988
+ * `recipient` from `fromTeamId` on `teamRowId`, stamped with `policy`, through
989
+ * its own send door. This function never decides what leaves or whether it
990
+ * may.
991
+ */
992
+ declare function fireShareEvent(policies: readonly SharePolicyDoc[] | null | undefined, event: ShareEvent | null | undefined, options?: {
993
+ readonly alreadyFired?: Iterable<string> | null;
994
+ readonly teamRows?: readonly ShareTeamRowLike[] | null;
995
+ }): FiredShare[];
996
+
997
+ export { type AccountSharePurposePolicy, type EffectiveSharingCeiling, type EffectiveSharingCeilingInputs, type FiredShare, HTI_SHARE_PLATFORM_PURPOSE_ENABLED, HTI_SHARE_PLATFORM_REQUIRED_BY_PURPOSE, HTI_SHARE_PLATFORM_STARTER, HTI_SHARE_PLATFORM_STARTER_SOURCE, INFORMATION_SCOPE_FIELD_HOME_ROWS, SHARE_EVENT, SHARE_LEVEL_LABEL, SHARE_PLATFORM_STATE_LABEL, SHARE_POSTURE_RANK, SHARE_REPORTING_PURPOSES, SHARE_TRIGGER_EVENTS, SHARING_CEILING_DEFAULT_ROW_KEY, SHARING_CEILING_EXTERNAL_ROW_KEY, SHARING_CEILING_SCOPE_VERSION, type ShareAttachmentIndex, type ShareCategoryEntry, type ShareDefaultScopeOptions, type ShareEvent, type ShareLevel, type ShareListener, type ShareNamedPolicy, type SharePlatformDefault, type SharePlatformState, type SharePolicyAssignment, type SharePolicyDoc, type SharePosture, type ShareRecipient, type ShareResolution, type ShareResolveInput, type ShareTeamRowLike, type ShareTriggerEventCode, type SharingCeilingAllowed, type SharingCeilingCellLike, type SharingCeilingRung, type SharingCeilingScope, type SharingPlatformStarter, type SharingPurposeLists, type SharingScopeCeiling, type SharingScopeEdits, accountSharePurposePolicy, attachmentIndexFromPolicies, ceilingCoverage, derivePlatformDefault, effectiveCeiling, fireShareEvent, firedShareKey, hasOwnScopeContent, intersectSharingCeilingLists, isCeilingCoverageRow, isPermittedByCeiling, isSharingPurposeDisabled, liveCategories, maskSelectionToCeiling, matchTeamRow, platformDefaultFor, policyIsShareListener, resolveShare, rowsExpandedByCeiling, rowsOutsideCeiling, rowsOverCeiling, scopeListCovers, scopeListStrictlyCovers, scopeRowWithinCeiling, shareDefaultScopeFor, shareListenersFor, shareRowCeiling, shareTriggerLabel, sharingCeilingCellList, sharingCeilingRowKey, sharingScopeEditsFromCells, systemCategoryOf };
@@ -497,6 +497,16 @@ type SharePolicyAssignment = {
497
497
  readonly teamRowId: string;
498
498
  readonly teamId?: string;
499
499
  readonly partnerId?: string | null;
500
+ /**
501
+ * The other end of the row, as the Admin Hub stores it on the link
502
+ * (data.js `policyRecord`): `{ type: "team", id }` names a receiving
503
+ * team — one of the account's own (no `partnerId`) or the partner's.
504
+ * The ladder does not read it (the row decides); `fireShareEvent` does.
505
+ */
506
+ readonly with?: {
507
+ readonly type?: string;
508
+ readonly id?: string;
509
+ } | null;
500
510
  };
501
511
  /** A policy document as the Admin Hub stores it (data.js `policyRecord` L53540ff). */
502
512
  interface SharePolicyDoc {
@@ -523,9 +533,19 @@ interface SharePolicyDoc {
523
533
  readonly edited?: boolean;
524
534
  /** `false` = retired: never governs. */
525
535
  readonly active?: boolean;
526
- /** `answers: "received"` (K13-9b): a share-back policy never governs a share you start. */
536
+ /**
537
+ * `answers: "received"` (K13-9b): a share-back policy never governs a share you start.
538
+ * `on` (K13-9a): the CVC-285 event names a LISTENER fires on — read by
539
+ * `fireShareEvent`, never by the ladder.
540
+ */
527
541
  readonly trigger?: {
528
542
  readonly answers?: string;
543
+ readonly on?: readonly string[];
544
+ } | null;
545
+ /** CVC-85 cadences the policy grants; `ongoing` + a trigger makes it a listener (K13-9a). */
546
+ readonly cadences?: {
547
+ readonly ongoing?: boolean;
548
+ readonly automatic?: boolean;
529
549
  } | null;
530
550
  }
531
551
  /** The Platform default for one purpose, as the four states (data.js `platformStarterScope` L53719ff). */
@@ -782,4 +802,196 @@ declare function shareRowCeiling(resolution: Pick<ShareResolution, "allowed" | "
782
802
  */
783
803
  declare function resolveShare(input: ShareResolveInput): ShareResolution;
784
804
 
785
- export { type AccountSharePurposePolicy, type EffectiveSharingCeiling, type EffectiveSharingCeilingInputs, HTI_SHARE_PLATFORM_PURPOSE_ENABLED, HTI_SHARE_PLATFORM_REQUIRED_BY_PURPOSE, HTI_SHARE_PLATFORM_STARTER, HTI_SHARE_PLATFORM_STARTER_SOURCE, INFORMATION_SCOPE_FIELD_HOME_ROWS, SHARE_LEVEL_LABEL, SHARE_PLATFORM_STATE_LABEL, SHARE_POSTURE_RANK, SHARE_REPORTING_PURPOSES, SHARING_CEILING_DEFAULT_ROW_KEY, SHARING_CEILING_EXTERNAL_ROW_KEY, SHARING_CEILING_SCOPE_VERSION, type ShareAttachmentIndex, type ShareCategoryEntry, type ShareDefaultScopeOptions, type ShareLevel, type ShareNamedPolicy, type SharePlatformDefault, type SharePlatformState, type SharePolicyAssignment, type SharePolicyDoc, type SharePosture, type ShareRecipient, type ShareResolution, type ShareResolveInput, type ShareTeamRowLike, type SharingCeilingAllowed, type SharingCeilingCellLike, type SharingCeilingRung, type SharingCeilingScope, type SharingPlatformStarter, type SharingPurposeLists, type SharingScopeCeiling, type SharingScopeEdits, accountSharePurposePolicy, attachmentIndexFromPolicies, ceilingCoverage, derivePlatformDefault, effectiveCeiling, hasOwnScopeContent, intersectSharingCeilingLists, isCeilingCoverageRow, isPermittedByCeiling, isSharingPurposeDisabled, liveCategories, maskSelectionToCeiling, matchTeamRow, platformDefaultFor, resolveShare, rowsExpandedByCeiling, rowsOutsideCeiling, rowsOverCeiling, scopeListCovers, scopeListStrictlyCovers, scopeRowWithinCeiling, shareDefaultScopeFor, shareRowCeiling, sharingCeilingCellList, sharingCeilingRowKey, sharingScopeEditsFromCells, systemCategoryOf };
805
+ /**
806
+ * EVENT-DRIVEN SHARING — which listeners an event fires (Kickoff 13 build
807
+ * item 9a; Crysta 2026-10-19 14:26 "enabling vs firing"; home ruled
808
+ * 2026-11-01: platform-common exports `ShareEvent` + `fireShareEvent(policies,
809
+ * event)` as a pure function, and each app calls it after commit at session
810
+ * submit and case close).
811
+ *
812
+ * Contract of record: platform-prototype `src/data.js` — `TRIGGER_EVENTS`,
813
+ * `policyIsListener`, `listenersFor`, `fireShareEvent` (K13-9a
814
+ * EVENT-LISTENER 2026-10-22).
815
+ *
816
+ * ENABLING is a Policy with the `ongoing` cadence and a trigger, linked team
817
+ * → team or team → partner: standing permission, authored by the Member
818
+ * Admin. FIRING writes an ORDINARY share — the policy's purpose and version
819
+ * on it — down the normal notify → review → claim path; only the author
820
+ * differs.
821
+ *
822
+ * This module answers ONE question and decides nothing else: given the
823
+ * sending account's policy documents and an event raised by a team, which
824
+ * listeners fire, and to whom. Everything a manual share of that purpose
825
+ * would be held to still applies and stays where it lives — the app sends
826
+ * each answer through its own send door: `resolveShare` for what may leave
827
+ * (and the policy's posture — `approval` waits, `blocked` holds), the release
828
+ * for a partner (one that covers the `ongoing` cadence), the account's
829
+ * catalog, the floor. A fired share is never a way around a rule.
830
+ *
831
+ * THE CALLER'S TWO DUTIES. (1) A link is read from the policy document's own
832
+ * `assignments`; pass the account's team rows as `options.teamRows` (or check
833
+ * `teamRowId` against your row store before sending) so a link whose row was
834
+ * deleted, or no longer says what the document says, fires nothing. (2) An
835
+ * event that can happen more than once on one subject (a note, a service, a
836
+ * status change) needs its own `ref`, or the second is taken for the first.
837
+ *
838
+ * Pure: no I/O, no clock, no randomness. The same input gives the same
839
+ * output, so a caller can run it twice and compare `key`s to fire each
840
+ * listener ONCE per event per subject (pass the keys already written as
841
+ * `alreadyFired`).
842
+ */
843
+
844
+ /**
845
+ * The events a listener may name. A trigger is a flag over EXISTING codes —
846
+ * the CVC-285 event names the platform already emits — and mints no new CVC
847
+ * (open point 5's default). The subset a case or a share can raise, in the
848
+ * prototype's order and words.
849
+ */
850
+ declare const SHARE_TRIGGER_EVENTS: readonly [{
851
+ readonly code: "sessionSubmitted";
852
+ readonly label: "Session submitted";
853
+ readonly group: "case";
854
+ }, {
855
+ readonly code: "caseOpened";
856
+ readonly label: "Case opened";
857
+ readonly group: "case";
858
+ }, {
859
+ readonly code: "caseStatusChanged";
860
+ readonly label: "Case status changed";
861
+ readonly group: "case";
862
+ }, {
863
+ readonly code: "caseCloseRuled";
864
+ readonly label: "Case closed";
865
+ readonly group: "case";
866
+ }, {
867
+ readonly code: "determinationIssued";
868
+ readonly label: "Determination issued";
869
+ readonly group: "case";
870
+ }, {
871
+ readonly code: "serviceLogged";
872
+ readonly label: "Service logged";
873
+ readonly group: "case";
874
+ }, {
875
+ readonly code: "noteAdded";
876
+ readonly label: "Note added";
877
+ readonly group: "case";
878
+ }, {
879
+ readonly code: "shareClaimed";
880
+ readonly label: "Share you sent claimed";
881
+ readonly group: "share";
882
+ }, {
883
+ readonly code: "referralClaimed";
884
+ readonly label: "Referral you sent claimed";
885
+ readonly group: "share";
886
+ }, {
887
+ readonly code: "shareAcknowledged";
888
+ readonly label: "Share you sent acknowledged";
889
+ readonly group: "share";
890
+ }];
891
+ type ShareTriggerEventCode = (typeof SHARE_TRIGGER_EVENTS)[number]["code"];
892
+ /** The two events the apps raise today (session submit · case close). */
893
+ declare const SHARE_EVENT: Readonly<{
894
+ readonly SESSION_SUBMITTED: "sessionSubmitted";
895
+ readonly CASE_CLOSED: "caseCloseRuled";
896
+ }>;
897
+ /** The words a person reads for a trigger code (the code itself when unknown). */
898
+ declare function shareTriggerLabel(code: string): string;
899
+ /** Something that happened on a case or a session, raised by the team that did it. */
900
+ interface ShareEvent {
901
+ /** The CVC-285 event name (`SHARE_EVENT`, `SHARE_TRIGGER_EVENTS`). */
902
+ readonly event: string;
903
+ /**
904
+ * The ACTING team — a listener is a link FROM a team, so an event with no
905
+ * team fires nothing.
906
+ */
907
+ readonly teamId: string | null | undefined;
908
+ /** Informational: `policies` must already be the sending account's documents. */
909
+ readonly accountId?: string | null;
910
+ readonly caseId?: string | null;
911
+ readonly sessionId?: string | null;
912
+ /**
913
+ * What the event is about, for the once-only key. Default: the session id
914
+ * for `sessionSubmitted`; for every other event the case id, else the
915
+ * session id; else none (every such event shares one key). Pass it
916
+ * explicitly for an event that can repeat on one case.
917
+ */
918
+ readonly ref?: string | null;
919
+ }
920
+ /** One listener: a policy with the `ongoing` cadence and a trigger, on one team link. */
921
+ interface ShareListener {
922
+ readonly policy: {
923
+ readonly id: string;
924
+ readonly familyId: string;
925
+ readonly name: string;
926
+ readonly version: number;
927
+ };
928
+ readonly purpose: string;
929
+ readonly fromTeamId: string;
930
+ /** The link's row — what `resolveShare` takes as `teamRowId`. */
931
+ readonly teamRowId: string;
932
+ /** Who it sends to, in the resolver's own vocabulary. */
933
+ readonly recipient: Extract<ShareRecipient, {
934
+ kind: "partner";
935
+ } | {
936
+ kind: "sibling_team";
937
+ }>;
938
+ /** A team → partner-team link names the partner's team; else `null`. */
939
+ readonly partnerTeamId: string | null;
940
+ /** The events it listens for. */
941
+ readonly events: readonly string[];
942
+ }
943
+ /** One listener an event raised — the share the app is to write. */
944
+ interface FiredShare extends ShareListener {
945
+ readonly event: string;
946
+ readonly ref: string | null;
947
+ /**
948
+ * Stable for one event × subject × policy × sending team × recipient: the
949
+ * same event on the same case fires each listener ONCE. Opaque — compare
950
+ * it, never parse it.
951
+ */
952
+ readonly key: string;
953
+ }
954
+ /**
955
+ * A policy that listens: live, `ongoing` cadence, at least one trigger event
956
+ * (data.js `policyIsListener`) — and NOT a share-back policy
957
+ * (`trigger.answers === "received"`, K13-9b), which answers a share received
958
+ * and never fires on a case event.
959
+ */
960
+ declare function policyIsShareListener(p: SharePolicyDoc | null | undefined): boolean;
961
+ /**
962
+ * The listeners linked FROM one team (data.js `listenersFor`): each listening
963
+ * policy × each of its team → team / team → partner links whose sending team
964
+ * is `teamId`. A link that names no sending team, a different team, or no
965
+ * target is not a listener for this team. The policy must also be the one
966
+ * that HOLDS the row's cell for its purpose (`attachmentIndexFromPolicies` —
967
+ * two live documents on one cell: the later wins, exactly as the ladder
968
+ * reads it), so the share a listener fires is governed by that same policy.
969
+ * Two links of one policy to the same place are one listener (the first, in
970
+ * document order). `options.event` keeps only the policies listening for
971
+ * that event; `options.teamRows`, when given, drops a link whose row is gone
972
+ * or disagrees with it.
973
+ */
974
+ declare function shareListenersFor(policies: readonly SharePolicyDoc[] | null | undefined, teamId: string | null | undefined, options?: {
975
+ readonly event?: string | null;
976
+ readonly teamRows?: readonly ShareTeamRowLike[] | null;
977
+ }): ShareListener[];
978
+ /** The once-only key of one fired share (see `FiredShare.key`). */
979
+ declare function firedShareKey(event: string, ref: string | null, listener: Pick<ShareListener, "policy" | "fromTeamId" | "recipient" | "partnerTeamId">): string;
980
+ /**
981
+ * FIRING (data.js `fireShareEvent`, the pure half): the listeners linked from
982
+ * the acting team that listen for this event, each as the share to write.
983
+ * Call it AFTER the event's own write commits. `[]` when the event names no
984
+ * team or no event, when nothing listens — and for every listener whose key
985
+ * is in `alreadyFired` (what the app has written for this event before).
986
+ *
987
+ * The app then sends each one as an ordinary share of `purpose` to
988
+ * `recipient` from `fromTeamId` on `teamRowId`, stamped with `policy`, through
989
+ * its own send door. This function never decides what leaves or whether it
990
+ * may.
991
+ */
992
+ declare function fireShareEvent(policies: readonly SharePolicyDoc[] | null | undefined, event: ShareEvent | null | undefined, options?: {
993
+ readonly alreadyFired?: Iterable<string> | null;
994
+ readonly teamRows?: readonly ShareTeamRowLike[] | null;
995
+ }): FiredShare[];
996
+
997
+ export { type AccountSharePurposePolicy, type EffectiveSharingCeiling, type EffectiveSharingCeilingInputs, type FiredShare, HTI_SHARE_PLATFORM_PURPOSE_ENABLED, HTI_SHARE_PLATFORM_REQUIRED_BY_PURPOSE, HTI_SHARE_PLATFORM_STARTER, HTI_SHARE_PLATFORM_STARTER_SOURCE, INFORMATION_SCOPE_FIELD_HOME_ROWS, SHARE_EVENT, SHARE_LEVEL_LABEL, SHARE_PLATFORM_STATE_LABEL, SHARE_POSTURE_RANK, SHARE_REPORTING_PURPOSES, SHARE_TRIGGER_EVENTS, SHARING_CEILING_DEFAULT_ROW_KEY, SHARING_CEILING_EXTERNAL_ROW_KEY, SHARING_CEILING_SCOPE_VERSION, type ShareAttachmentIndex, type ShareCategoryEntry, type ShareDefaultScopeOptions, type ShareEvent, type ShareLevel, type ShareListener, type ShareNamedPolicy, type SharePlatformDefault, type SharePlatformState, type SharePolicyAssignment, type SharePolicyDoc, type SharePosture, type ShareRecipient, type ShareResolution, type ShareResolveInput, type ShareTeamRowLike, type ShareTriggerEventCode, type SharingCeilingAllowed, type SharingCeilingCellLike, type SharingCeilingRung, type SharingCeilingScope, type SharingPlatformStarter, type SharingPurposeLists, type SharingScopeCeiling, type SharingScopeEdits, accountSharePurposePolicy, attachmentIndexFromPolicies, ceilingCoverage, derivePlatformDefault, effectiveCeiling, fireShareEvent, firedShareKey, hasOwnScopeContent, intersectSharingCeilingLists, isCeilingCoverageRow, isPermittedByCeiling, isSharingPurposeDisabled, liveCategories, maskSelectionToCeiling, matchTeamRow, platformDefaultFor, policyIsShareListener, resolveShare, rowsExpandedByCeiling, rowsOutsideCeiling, rowsOverCeiling, scopeListCovers, scopeListStrictlyCovers, scopeRowWithinCeiling, shareDefaultScopeFor, shareListenersFor, shareRowCeiling, shareTriggerLabel, sharingCeilingCellList, sharingCeilingRowKey, sharingScopeEditsFromCells, systemCategoryOf };
@@ -937,7 +937,9 @@ function resolveShare(input) {
937
937
  const teamExcludedItems = [];
938
938
  let teamExcludedReason = null;
939
939
  const outside = (covered) => items.filter(
940
- (r) => !covered(r) && !items.some((d) => d !== r && covered(d) && scope.ancestorsOf(d).includes(r))
940
+ (r) => !covered(r) && !items.some(
941
+ (d) => d !== r && covered(d) && scope.ancestorsOf(d).includes(r)
942
+ )
941
943
  );
942
944
  const addExcluded = (rows, why) => {
943
945
  for (const r of rows)
@@ -1007,7 +1009,8 @@ function resolveShare(input) {
1007
1009
  const why = `Outside what your team's \u201C${tcNamed?.name}\u201D policy allows`;
1008
1010
  const outRows = /* @__PURE__ */ new Set();
1009
1011
  if (tcScope !== null && !scopeListStrictlyCovers(scope, tcScope, g)) {
1010
- for (const r of outside((x) => scopeListCovers(scope, tcScope, g, x))) outRows.add(r);
1012
+ for (const r of outside((x) => scopeListCovers(scope, tcScope, g, x)))
1013
+ outRows.add(r);
1011
1014
  }
1012
1015
  const tcRows = own2(tcItems, g);
1013
1016
  if (isStringList2(tcRows)) {
@@ -1065,16 +1068,151 @@ function resolveShare(input) {
1065
1068
  rulePath
1066
1069
  };
1067
1070
  }
1071
+
1072
+ // src/sharingCeiling/fireShareEvent.ts
1073
+ var SHARE_TRIGGER_EVENTS = Object.freeze([
1074
+ { code: "sessionSubmitted", label: "Session submitted", group: "case" },
1075
+ { code: "caseOpened", label: "Case opened", group: "case" },
1076
+ { code: "caseStatusChanged", label: "Case status changed", group: "case" },
1077
+ { code: "caseCloseRuled", label: "Case closed", group: "case" },
1078
+ {
1079
+ code: "determinationIssued",
1080
+ label: "Determination issued",
1081
+ group: "case"
1082
+ },
1083
+ { code: "serviceLogged", label: "Service logged", group: "case" },
1084
+ { code: "noteAdded", label: "Note added", group: "case" },
1085
+ { code: "shareClaimed", label: "Share you sent claimed", group: "share" },
1086
+ {
1087
+ code: "referralClaimed",
1088
+ label: "Referral you sent claimed",
1089
+ group: "share"
1090
+ },
1091
+ {
1092
+ code: "shareAcknowledged",
1093
+ label: "Share you sent acknowledged",
1094
+ group: "share"
1095
+ }
1096
+ ]);
1097
+ var SHARE_EVENT = Object.freeze({
1098
+ SESSION_SUBMITTED: "sessionSubmitted",
1099
+ CASE_CLOSED: "caseCloseRuled"
1100
+ });
1101
+ function shareTriggerLabel(code) {
1102
+ return SHARE_TRIGGER_EVENTS.find((t) => t.code === code)?.label ?? code;
1103
+ }
1104
+ var str = (v) => typeof v === "string" && v !== "";
1105
+ function policyIsShareListener(p) {
1106
+ if (p === null || p === void 0 || typeof p !== "object") return false;
1107
+ if (p.active === false) return false;
1108
+ if (p.cadences?.ongoing !== true) return false;
1109
+ const on = p.trigger?.on;
1110
+ if (!Array.isArray(on) || !on.some(str)) return false;
1111
+ return p.trigger?.answers !== "received";
1112
+ }
1113
+ function linkTarget(a) {
1114
+ const withTeam = a.with !== null && typeof a.with === "object" && a.with.type === "team" && str(a.with.id) ? a.with.id : null;
1115
+ if (str(a.partnerId)) {
1116
+ return {
1117
+ recipient: { kind: "partner", id: a.partnerId },
1118
+ partnerTeamId: withTeam
1119
+ };
1120
+ }
1121
+ if (withTeam !== null) {
1122
+ return {
1123
+ recipient: { kind: "sibling_team", teamId: withTeam },
1124
+ partnerTeamId: null
1125
+ };
1126
+ }
1127
+ return null;
1128
+ }
1129
+ var targetKey = (l) => l.recipient.kind === "partner" ? ["partner", l.recipient.id, l.partnerTeamId] : ["team", l.recipient.teamId, null];
1130
+ function rowAgrees(rows, a, target) {
1131
+ const row = rows.find(
1132
+ (r) => r !== null && typeof r === "object" && r.id === a.teamRowId
1133
+ );
1134
+ if (row === void 0 || row.myTeamId !== a.teamId) return false;
1135
+ const theirTeam = row.their?.type === "team" && str(row.their.id) ? row.their.id : null;
1136
+ return target.recipient.kind === "sibling_team" ? theirTeam === target.recipient.teamId : theirTeam === target.partnerTeamId;
1137
+ }
1138
+ function shareListenersFor(policies, teamId, options = {}) {
1139
+ if (!Array.isArray(policies) || !str(teamId)) return [];
1140
+ const cells = attachmentIndexFromPolicies(policies).teamRows;
1141
+ const rows = Array.isArray(options.teamRows) ? options.teamRows : null;
1142
+ const out = [];
1143
+ const seen = /* @__PURE__ */ new Set();
1144
+ for (const p of policies) {
1145
+ if (!policyIsShareListener(p) || !str(p.id) || !str(p.purpose)) continue;
1146
+ const events = (p.trigger?.on ?? []).filter(str);
1147
+ if (str(options.event) && !events.includes(options.event)) continue;
1148
+ for (const a of Array.isArray(p.assignments) ? p.assignments : []) {
1149
+ if (a === null || typeof a !== "object" || a.scope !== "team_pair")
1150
+ continue;
1151
+ if (!str(a.teamRowId) || a.teamId !== teamId) continue;
1152
+ if (cells[a.teamRowId]?.[p.purpose] !== p.id) continue;
1153
+ const target = linkTarget(a);
1154
+ if (target === null) continue;
1155
+ if (rows !== null && !rowAgrees(rows, a, target)) continue;
1156
+ if (target.recipient.kind === "sibling_team" && target.recipient.teamId === teamId)
1157
+ continue;
1158
+ const dedupe = JSON.stringify([p.id, ...targetKey(target)]);
1159
+ if (seen.has(dedupe)) continue;
1160
+ seen.add(dedupe);
1161
+ out.push({
1162
+ policy: {
1163
+ id: p.id,
1164
+ familyId: str(p.familyId) ? p.familyId : p.id,
1165
+ name: str(p.name) ? p.name : p.id,
1166
+ version: parseInt(String(p.version), 10) || 1
1167
+ },
1168
+ purpose: p.purpose,
1169
+ fromTeamId: teamId,
1170
+ teamRowId: a.teamRowId,
1171
+ ...target,
1172
+ events
1173
+ });
1174
+ }
1175
+ }
1176
+ return out;
1177
+ }
1178
+ function firedShareKey(event, ref, listener) {
1179
+ return JSON.stringify([
1180
+ event,
1181
+ ref,
1182
+ listener.policy.id,
1183
+ listener.fromTeamId,
1184
+ ...targetKey(listener)
1185
+ ]);
1186
+ }
1187
+ function fireShareEvent(policies, event, options = {}) {
1188
+ if (event === null || event === void 0 || !str(event.event)) return [];
1189
+ const session = str(event.sessionId) ? event.sessionId : null;
1190
+ const kase = str(event.caseId) ? event.caseId : null;
1191
+ const ref = str(event.ref) ? event.ref : event.event === SHARE_EVENT.SESSION_SUBMITTED ? session ?? kase : kase ?? session;
1192
+ const done = new Set(options.alreadyFired ?? []);
1193
+ const fired = [];
1194
+ for (const l of shareListenersFor(policies, event.teamId, {
1195
+ event: event.event,
1196
+ teamRows: options.teamRows ?? null
1197
+ })) {
1198
+ const key = firedShareKey(event.event, ref, l);
1199
+ if (done.has(key)) continue;
1200
+ fired.push({ ...l, event: event.event, ref, key });
1201
+ }
1202
+ return fired;
1203
+ }
1068
1204
  export {
1069
1205
  HTI_SHARE_PLATFORM_PURPOSE_ENABLED,
1070
1206
  HTI_SHARE_PLATFORM_REQUIRED_BY_PURPOSE,
1071
1207
  HTI_SHARE_PLATFORM_STARTER,
1072
1208
  HTI_SHARE_PLATFORM_STARTER_SOURCE,
1073
1209
  INFORMATION_SCOPE_FIELD_HOME_ROWS,
1210
+ SHARE_EVENT,
1074
1211
  SHARE_LEVEL_LABEL,
1075
1212
  SHARE_PLATFORM_STATE_LABEL,
1076
1213
  SHARE_POSTURE_RANK,
1077
1214
  SHARE_REPORTING_PURPOSES,
1215
+ SHARE_TRIGGER_EVENTS,
1078
1216
  SHARING_CEILING_DEFAULT_ROW_KEY,
1079
1217
  SHARING_CEILING_EXTERNAL_ROW_KEY,
1080
1218
  SHARING_CEILING_SCOPE_VERSION,
@@ -1083,6 +1221,8 @@ export {
1083
1221
  ceilingCoverage,
1084
1222
  derivePlatformDefault,
1085
1223
  effectiveCeiling,
1224
+ fireShareEvent,
1225
+ firedShareKey,
1086
1226
  hasOwnScopeContent,
1087
1227
  intersectSharingCeilingLists,
1088
1228
  isCeilingCoverageRow,
@@ -1092,6 +1232,7 @@ export {
1092
1232
  maskSelectionToCeiling,
1093
1233
  matchTeamRow,
1094
1234
  platformDefaultFor,
1235
+ policyIsShareListener,
1095
1236
  resolveShare,
1096
1237
  rowsExpandedByCeiling,
1097
1238
  rowsOutsideCeiling,
@@ -1100,7 +1241,9 @@ export {
1100
1241
  scopeListStrictlyCovers,
1101
1242
  scopeRowWithinCeiling,
1102
1243
  shareDefaultScopeFor,
1244
+ shareListenersFor,
1103
1245
  shareRowCeiling,
1246
+ shareTriggerLabel,
1104
1247
  sharingCeilingCellList,
1105
1248
  sharingCeilingRowKey,
1106
1249
  sharingScopeEditsFromCells,