@htilabs/platform-common-models 0.40.0 → 0.42.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 (40) hide show
  1. package/README.md +149 -0
  2. package/dist/index.cjs +677 -0
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +1 -1
  5. package/dist/index.d.ts +1 -1
  6. package/dist/index.js +658 -0
  7. package/dist/index.js.map +1 -1
  8. package/dist/share-rules/index.cjs +822 -0
  9. package/dist/share-rules/index.cjs.map +1 -0
  10. package/dist/share-rules/index.d.cts +804 -0
  11. package/dist/share-rules/index.d.ts +804 -0
  12. package/dist/share-rules/index.js +736 -0
  13. package/dist/share-rules/index.js.map +1 -0
  14. package/dist/sharing-ceiling/index.cjs +679 -2
  15. package/dist/sharing-ceiling/index.cjs.map +1 -1
  16. package/dist/sharing-ceiling/index.d.cts +461 -1
  17. package/dist/sharing-ceiling/index.d.ts +461 -1
  18. package/dist/sharing-ceiling/index.js +659 -1
  19. package/dist/sharing-ceiling/index.js.map +1 -1
  20. package/package.json +6 -1
  21. package/src/shareRules/__tests__/caseShareLane.test.ts +259 -0
  22. package/src/shareRules/__tests__/magicLinkAddresses.test.ts +107 -0
  23. package/src/shareRules/__tests__/platformApps.test.ts +133 -0
  24. package/src/shareRules/__tests__/releaseTerms.test.ts +358 -0
  25. package/src/shareRules/__tests__/senderRoiPosture.test.ts +284 -0
  26. package/src/shareRules/__tests__/sharingMethods.test.ts +105 -0
  27. package/src/shareRules/caseShareLane.ts +289 -0
  28. package/src/shareRules/index.ts +31 -0
  29. package/src/shareRules/magicLinkAddresses.ts +185 -0
  30. package/src/shareRules/platformApps.ts +168 -0
  31. package/src/shareRules/releaseTerms.ts +359 -0
  32. package/src/shareRules/reportPurposes.ts +50 -0
  33. package/src/shareRules/senderRoiPosture.ts +296 -0
  34. package/src/shareRules/sharingMethods.ts +204 -0
  35. package/src/sharingCeiling/__tests__/resolveShare.test.ts +1305 -0
  36. package/src/sharingCeiling/__tests__/threadLift.test.ts +353 -0
  37. package/src/sharingCeiling/coverage.ts +63 -0
  38. package/src/sharingCeiling/defaults.ts +106 -0
  39. package/src/sharingCeiling/index.ts +13 -1
  40. package/src/sharingCeiling/resolve.ts +1278 -0
@@ -314,5 +314,465 @@ declare function rowsExpandedByCeiling(scope: SharingCeilingScope, allowed: Shar
314
314
  * result.
315
315
  */
316
316
  declare function maskSelectionToCeiling(scope: SharingCeilingScope, selection: readonly string[] | null | undefined, allowed: SharingCeilingAllowed): string[];
317
+ /**
318
+ * The part of a ceiling a scope check reads: the v4 rows that may leave, or
319
+ * `null` when no ceiling binds.
320
+ */
321
+ interface SharingScopeCeiling {
322
+ readonly allowed: ReadonlySet<string> | readonly string[] | null;
323
+ }
324
+ /**
325
+ * Whether the ceiling permits one v4 ROW — the coverage rule
326
+ * ({@link scopeRowWithinCeiling}).
327
+ *
328
+ * - `null` ceiling or `allowed: null` ⇒ permitted (no ceiling binds).
329
+ * - System metadata (any row under `system`) ⇒ permitted (GDR 5.17
330
+ * clause 5 — provenance rides).
331
+ * - A code outside the tree ⇒ NOT permitted (fail closed).
332
+ */
333
+ declare function isPermittedByCeiling(scope: SharingCeilingScope, ceiling: SharingScopeCeiling | null, code: string): boolean;
334
+ /**
335
+ * What BOTH of two ceiling lists permit: a row of either list that is within
336
+ * the other (the coverage rule). A composer intersects its selected
337
+ * recipients' ceilings with this — one selection serves every recipient, so
338
+ * the narrowest wins.
339
+ */
340
+ declare function intersectSharingCeilingLists(scope: SharingCeilingScope, a: ReadonlySet<string> | readonly string[], b: ReadonlySet<string> | readonly string[]): string[];
341
+
342
+ /**
343
+ * The account's per-purpose DEFAULT share scope (C12b) — the prototype's
344
+ * `shareDefaultScopeFor`: the v4 rows a share of one purpose carries by the
345
+ * ACCOUNT's rule, before any recipient is named. The account's own
346
+ * `__default__` cell for the purpose, else the platform starter's
347
+ * `scopeByPurpose[purpose]`; `[]` when the purpose is off.
348
+ *
349
+ * Lifted unchanged from Thread `@thread/shared` `sharingCeiling.ts`
350
+ * L383-L427 @ thread develop f021be2 (`accountSharePurposePolicy`), so Thread
351
+ * and PAVE compute it once. Exported under the prototype's name
352
+ * {@link shareDefaultScopeFor}; {@link accountSharePurposePolicy} is the same
353
+ * function, kept so Thread's call sites do not change.
354
+ *
355
+ * It is the chain's `account_default` → `platform_default` tail
356
+ * (`effectiveCeiling`, ./chain.ts) — what every recipient without a partner
357
+ * rule is held to: the composer's and the release wizard's "your account's
358
+ * default for <purpose>" preset. Canon: prototype
359
+ * `HTI-LEADS-PAVE-Thread-prototype.html` @ d85f05b7 `shareEffectiveCeiling`
360
+ * L327966-L328090 (the chain's tail L328053-L328058); the off reading is
361
+ * clamp 1 (platform-prototype `src/data.js` @ a6f1f3a L51352-L51354).
362
+ *
363
+ * Pure: no mongoose, no I/O, no SOT import.
364
+ */
365
+
366
+ /**
367
+ * The account's standing on ONE share purpose, before any recipient is named
368
+ * — what the composer's purpose card shows beside each pill:
369
+ *
370
+ * - `off`: the purpose is switched off for the account (canon's clamp 1 —
371
+ * the platform row's `enabled: false`, or the account's own Share
372
+ * Purposes switch once the platform writes one; `isSharingPurposeDisabled`
373
+ * is the package's one test). An off purpose binds `[]` at every door, so
374
+ * the card renders it DISABLED-WITH-REASON (Terry ruling 2026-08-12:
375
+ * policy exclusions on this surface stay visible).
376
+ * - `accountDefault`: the v4 rows a share of that purpose carries by the
377
+ * ACCOUNT'S rule — the `__default__` cell the account authored, else the
378
+ * platform default (`starter.scopeByPurpose`); `[]` when off.
379
+ *
380
+ * `edits === null` (the store could not be read) → `[]` for every purpose,
381
+ * fail closed, like the ceiling itself.
382
+ */
383
+ interface AccountSharePurposePolicy {
384
+ readonly off: boolean;
385
+ readonly accountDefault: readonly string[];
386
+ }
387
+ /** The options {@link shareDefaultScopeFor} reads. */
388
+ interface ShareDefaultScopeOptions {
389
+ readonly starter?: SharingPlatformStarter;
390
+ /** The account's Share Purposes switches, when the platform writes them. */
391
+ readonly purposeOverrides?: Readonly<Record<string, boolean | undefined>> | null;
392
+ }
393
+ /**
394
+ * The account's default scope for `purpose` (see the module note). Total:
395
+ * never throws; a non-string entry in a stored list is dropped.
396
+ */
397
+ declare function shareDefaultScopeFor(edits: SharingScopeEdits | null | undefined, purpose: string, opts?: ShareDefaultScopeOptions): AccountSharePurposePolicy;
398
+ /**
399
+ * Thread's name for {@link shareDefaultScopeFor} — the SAME function (not a
400
+ * wrapper), kept so `@thread/shared` call sites do not change.
401
+ */
402
+ declare const accountSharePurposePolicy: typeof shareDefaultScopeFor;
403
+
404
+ /**
405
+ * THE share resolver (Kickoff 13, GDR § 5.79 "ONE resolver per runtime"): the
406
+ * one pure read Thread and PAVE call to learn, for one sender (account +
407
+ * team) × one recipient × one purpose, which POLICY governs and at which
408
+ * level, the posture, whether the share is excluded as a whole, and which
409
+ * information-scope categories may leave — with the sending team's own policy
410
+ * as a CEILING, the Platform default read as the FOUR STATES, and reports
411
+ * never blocked at the policy or partner layer. Every answer names policy ·
412
+ * version · level (CAM invariant 17).
413
+ *
414
+ * Contract of record: platform-prototype `src/data.js` @ becfab4 (K13-18) —
415
+ * - `governingPolicyFor` L54533ff: the team row, `hit()` (one policy =
416
+ * one purpose; a policy that ANSWERS shares received never governs a
417
+ * send), the ladder (pair row → [inside: account default for inside →
418
+ * the platform's inside starter] → relationship → account default →
419
+ * Platform default), `done()` (the sending team's own policy rides as a
420
+ * ceiling on every rung's answer when it is not itself the governing one);
421
+ * - `effectiveCeiling` L54879ff: the posture composition (L54977-L54994;
422
+ * `POSTURE_RANK` L53645), the whole-share exclusion, which list binds
423
+ * (K13-12, L55121-L55130) and the per-category clamps 0 · 4 · 4a · 4b · 5 ·
424
+ * 5b · 5c · 5d · the group flip (L55140ff; 4 at L55165, 4b at L55185);
425
+ * - `platformStarterScope` / `starterDerivedState` L53708-L53760: the
426
+ * Platform default as the four CVC-133 states (`SHARE_STATE_KEYS` L53697,
427
+ * `SCOPE_LOCK_LABEL` L53698);
428
+ * - `scopeListCovers` L54696-L54706 (HANDOFF K13-14: a stored list may name
429
+ * a category, a kind above it or a row of it — never read it with a flat
430
+ * `indexOf`).
431
+ * Behavioural specs: `tools/smoke/flows/one-resolver-k13.js` (A–G) and
432
+ * `sharing-four-state-k13.js` (A–C); the test suite beside this file carries
433
+ * their vectors.
434
+ *
435
+ * Deliberately NOT here (prototype storage artefacts or relationship-row
436
+ * facts the caller holds): the `byPurpose` virtual fork, the legacy
437
+ * `sharingPolicies` narrowing rows (#451 moved them onto cards), the partner
438
+ * row's direction / team-scoped gates and item `restrictions`, deconfliction /
439
+ * viewing / release / routing species. The legacy cell chain (`sharingScopeEdits`
440
+ * → `effectiveCeiling` in chain.ts) arrives as `legacyCeiling` and is applied
441
+ * exactly where data.js applies it (clamp 5; review M6: seeded partner rules
442
+ * stay a ceiling even over an authored policy).
443
+ *
444
+ * Fail-closed conventions (this module's, stricter than canon where noted):
445
+ * - an unknown purpose (no Platform default supplied) governs nothing —
446
+ * `governing: null`, every category withheld, `excluded` says why (canon's
447
+ * `governingPolicyFor` returns null and the read leaks unrestricted; the
448
+ * prototype masks it upstream with `purposeIsLive`);
449
+ * - a document's `infoScope: null` OR an absent `infoScope` is "no category
450
+ * list" and is honoured, exactly as data.js reads it
451
+ * (`Array.isArray(gp.policy.infoScope) ? … : null`, L54979 / L55124 —
452
+ * the inside starter and a field-limits-only team ceiling are written
453
+ * that way, flow G); an explicit `[]` binds an empty list (canon too);
454
+ * a value that is present but is not a list of strings reads as `[]`
455
+ * (stricter than canon, which reads it as no list);
456
+ * - the account's Information Scope (clamps 4 / 4b) starts from the codebook:
457
+ * a CVC-236 heightened category or row (`shareableDefault: false` —
458
+ * immigration & legal status, the full instrument narratives) stays OFF
459
+ * until the account turns it on (`accountScope.categoriesOn` / `rowsOn`),
460
+ * exactly as data.js reads `cg ? cg.shareable : seedG.shareable` and
461
+ * `saved4b ? saved4b.shareable : it.shareable` — a caller that passes no
462
+ * `accountScope` gets the codebook's defaults, never everything;
463
+ * - an assignment whose `scope` is not one of the five kinds is skipped; two live
464
+ * documents on one cell — a store's key forbids it — resolve to the LATER one in
465
+ * `policies` (deterministic), and a duplicated id to the later document;
466
+ * - a tree with no System-metadata category has nothing Required by itself, and an
467
+ * excluded share then lets nothing through at all.
468
+ *
469
+ * Pure: no I/O, no SOT import, copies never live references.
470
+ */
471
+
472
+ /** The purposes that are REPORTS (data.js `REPORTING_PURPOSES`, L53354) — derived from the purpose, never a caller flag. */
473
+ declare const SHARE_REPORTING_PURPOSES: ReadonlySet<string>;
474
+ type SharePosture = "open" | "approval" | "blocked";
475
+ /** data.js `POSTURE_RANK` L53645 — stricter is higher; a policy can only RAISE the posture. */
476
+ declare const SHARE_POSTURE_RANK: Readonly<Record<SharePosture, number>>;
477
+ /** The four states of the Platform default (CVC-133 keys; data.js `SHARE_STATE_KEYS` L53697). */
478
+ type SharePlatformState = "always" | "default_on" | "default_off" | "never";
479
+ /** The words a person reads for each state (data.js `SCOPE_LOCK_LABEL` L53698). */
480
+ declare const SHARE_PLATFORM_STATE_LABEL: Readonly<Record<SharePlatformState, string>>;
481
+ /** Where on the ladder the governing policy was found (data.js `ATTACH_LEVEL_LABEL` keys, L53646ff). */
482
+ type ShareLevel = "team_row" | "account_internal" | "inside_starter" | "relationship" | "agency_default" | "platform_starter";
483
+ declare const SHARE_LEVEL_LABEL: Readonly<Record<ShareLevel | "team", string>>;
484
+ /** One link of a policy to where it governs — a Relationship record (K13-3; data.js L53577-L53587). */
485
+ type SharePolicyAssignment = {
486
+ readonly scope: "account";
487
+ } | {
488
+ readonly scope: "account_internal";
489
+ } | {
490
+ readonly scope: "account_partner";
491
+ readonly partnerId: string;
492
+ } | {
493
+ readonly scope: "team";
494
+ readonly teamId: string;
495
+ } | {
496
+ readonly scope: "team_pair";
497
+ readonly teamRowId: string;
498
+ readonly teamId?: string;
499
+ readonly partnerId?: string | null;
500
+ };
501
+ /** A policy document as the Admin Hub stores it (data.js `policyRecord` L53540ff). */
502
+ interface SharePolicyDoc {
503
+ readonly id: string;
504
+ readonly familyId?: string;
505
+ /** Un-ledgered = v1 (`parseInt(p.version, 10) || 1`). */
506
+ readonly version?: number | string;
507
+ readonly name?: string;
508
+ /** ONE CVC-84 purpose (invariant 3). */
509
+ readonly purpose: string;
510
+ readonly species?: string;
511
+ readonly posture?: SharePosture | null;
512
+ readonly narrowOnly?: boolean;
513
+ /** v4 codes (categories, kinds, rows). `null` = no category list (no restriction at category grain). */
514
+ readonly infoScope?: readonly string[] | null;
515
+ /** Field-group grain: category → the rows of it that may leave (K13-5c). */
516
+ readonly infoScopeItems?: Readonly<Record<string, readonly string[]>> | null;
517
+ readonly assignments?: readonly SharePolicyAssignment[];
518
+ readonly origin?: {
519
+ readonly kind?: string;
520
+ readonly parentId?: string;
521
+ } | null;
522
+ /** `false` = still synced to the Platform default (K13-11): its list does not bind, the default's does. */
523
+ readonly edited?: boolean;
524
+ /** `false` = retired: never governs. */
525
+ readonly active?: boolean;
526
+ /** `answers: "received"` (K13-9b): a share-back policy never governs a share you start. */
527
+ readonly trigger?: {
528
+ readonly answers?: string;
529
+ } | null;
530
+ }
531
+ /** The Platform default for one purpose, as the four states (data.js `platformStarterScope` L53719ff). */
532
+ interface SharePlatformDefault {
533
+ readonly purpose: string;
534
+ /** The versioned tier document `pol-starter-<purpose>` (un-ledgered = 1). */
535
+ readonly version: number;
536
+ /** The STARTING scope — the lists `raw` as data.js keeps it: Required categories and `system` included, Blocked ones out. */
537
+ readonly raw: readonly string[];
538
+ /** category → state. */
539
+ readonly states: Readonly<Record<string, SharePlatformState>>;
540
+ /** Categories whose state is `always` (`system` not listed). */
541
+ readonly required: readonly string[];
542
+ /** Categories whose state is `never`. */
543
+ readonly blocked: readonly string[];
544
+ readonly edited?: boolean;
545
+ }
546
+ type ShareRecipient = {
547
+ readonly kind: "partner";
548
+ readonly id: string;
549
+ } | {
550
+ readonly kind: "external";
551
+ } | {
552
+ readonly kind: "sibling_team";
553
+ readonly teamId: string;
554
+ };
555
+ interface ShareResolveInput {
556
+ /** The v4 tree (an information-scope resolver, or anything with its four read methods). */
557
+ readonly scope: SharingCeilingScope;
558
+ /** Every policy document of the SENDING account (retired ones are skipped). */
559
+ readonly policies: readonly SharePolicyDoc[];
560
+ /** The Platform default for `purpose`; `null` = the purpose is unknown to the platform (fails closed). */
561
+ readonly platformDefault: SharePlatformDefault | null;
562
+ /** The sender: the account and, when the share is a team's, its team (`null` = a team-blind read: no pair row, no ceiling). */
563
+ /**
564
+ * The sender: its team when the share is a team's (`null` = a team-blind read: no pair row, no
565
+ * ceiling — the account's answer, not a team's). `accountId` is informational: `policies` must
566
+ * already be the SENDING account's documents (the resolver does not filter by account).
567
+ */
568
+ readonly sender: {
569
+ readonly accountId?: string;
570
+ readonly teamId: string | null;
571
+ };
572
+ /** The purpose's label for the Platform-default document names people read (`purpose` when absent). */
573
+ readonly purposeLabel?: string;
574
+ readonly recipient: ShareRecipient;
575
+ readonly purpose: string;
576
+ /** The matched team-to-team row (`matchTeamRow`), when the sender's team has one for this recipient. */
577
+ readonly teamRowId?: string | null;
578
+ /** Clamp 1: the purpose is switched off for the account (`isSharingPurposeDisabled` in chain.ts). Blocks reports too (flow M1). */
579
+ readonly purposeOff?: boolean;
580
+ /** The partner row's own posture, which a policy can only raise (data.js `effectiveCeiling`). Default `open`. */
581
+ readonly relationshipPosture?: SharePosture | null;
582
+ /**
583
+ * The legacy cell chain for callers still carrying `sharingScopeEdits`: pass `effectiveCeiling(...)`'s
584
+ * ANSWER (its `platform_default` rung is then ignored — the resolver reads that document itself;
585
+ * K13-12), or a plain list that binds as given; `null` / absent = none.
586
+ */
587
+ readonly legacyCeiling?: readonly string[] | EffectiveSharingCeiling | null;
588
+ /**
589
+ * The account's Information Scope (clamp 4 / 4b) as EXPLICIT choices over the codebook's
590
+ * defaults: `categoriesOff` / `rowsOff` = switched off; `categoriesOn` / `rowsOn` = a heightened
591
+ * (`shareableDefault: false`, CVC-236) category or row the account has turned ON. A code in
592
+ * neither list reads the codebook default — so heightened information stays off when this is
593
+ * absent (data.js `effectiveCeiling` clamps 4 / 4b). A code in both lists is off.
594
+ */
595
+ readonly accountScope?: {
596
+ readonly categoriesOff?: readonly string[];
597
+ readonly rowsOff?: readonly string[];
598
+ readonly categoriesOn?: readonly string[];
599
+ readonly rowsOn?: readonly string[];
600
+ } | null;
601
+ }
602
+ interface ShareNamedPolicy {
603
+ readonly id: string;
604
+ readonly familyId: string;
605
+ readonly name: string;
606
+ readonly version: number;
607
+ readonly level: ShareLevel | "team";
608
+ readonly levelLabel: string;
609
+ readonly posture: SharePosture | null;
610
+ readonly infoScope: string[] | null;
611
+ /** Field-group grain, when the document carries it (a copy). */
612
+ readonly infoScopeItems: Record<string, string[]> | null;
613
+ readonly edited: boolean;
614
+ readonly origin: string | null;
615
+ readonly rulePath: string;
616
+ }
617
+ interface ShareCategoryEntry {
618
+ readonly allowed: boolean;
619
+ readonly reason: string;
620
+ readonly rulePath: string;
621
+ /** Set when the Platform default marks the category Required (`always`): nothing account-grain removes it. */
622
+ readonly platformRequired: {
623
+ readonly rulePath: string;
624
+ } | null;
625
+ /** Rows under the platform safety floor — never leave. */
626
+ readonly floorItems: string[];
627
+ /** Rows the governing list / the account's heightened toggles / the ceiling leave out. */
628
+ readonly excludedItems: string[];
629
+ readonly excludedReason: string | null;
630
+ /** Rows the sending team's own policy leaves out (5d). */
631
+ readonly teamExcludedItems: string[];
632
+ readonly teamExcludedReason: string | null;
633
+ }
634
+ interface ShareResolution {
635
+ /** `false` = the share as a whole is excluded (`excluded` says why). */
636
+ readonly allowed: boolean;
637
+ readonly posture: SharePosture;
638
+ readonly postureSource: "relationship" | "policy" | "team_ceiling";
639
+ readonly excluded: {
640
+ readonly reason: string;
641
+ readonly rulePath: string;
642
+ } | null;
643
+ /** A reporting purpose under a `blocked` posture: never excluded; the note names what blocks ordinary sharing. */
644
+ readonly reportCarveOut: {
645
+ readonly note: string;
646
+ readonly rulePath: string;
647
+ } | null;
648
+ /** The policy that governs; `null` only for an unknown purpose (fails closed). */
649
+ readonly governing: ShareNamedPolicy | null;
650
+ /** The sending team's own policy for the purpose, when it is not itself the governing one. */
651
+ readonly teamCeiling: ShareNamedPolicy | null;
652
+ /** A share to a sibling team of the same account. */
653
+ readonly inside: boolean;
654
+ /** Every live category of the tree, in tree order. */
655
+ readonly scope: Readonly<Record<string, ShareCategoryEntry>>;
656
+ /** The categories with `allowed === true`, tree order — the list the coverage readers take. */
657
+ readonly allowedCategories: string[];
658
+ readonly rulePath: string;
659
+ }
660
+ /**
661
+ * data.js `scopeListCovers` (L54696-L54706), on the v4 tree: a non-array list
662
+ * covers everything; a category is covered when the list names it or an
663
+ * ANCESTOR (a kind such as `family`, a branch); with a row `it`, the row is
664
+ * covered when it or an ancestor is named; without one, a category is also
665
+ * covered when the list names any DESCENDANT of it (a row or grouping).
666
+ */
667
+ declare function scopeListCovers(scope: SharingCeilingScope, list: readonly string[] | null | undefined, categoryCode: string, rowCode?: string): boolean;
668
+ /** `scopeStrictCovers` (L54710ff): the list names the category or an ancestor — never a descendant. */
669
+ declare function scopeListStrictlyCovers(scope: SharingCeilingScope, list: readonly string[] | null | undefined, categoryCode: string): boolean;
670
+ /** The attachment index the ladder reads (data.js `effectiveAttachmentIndex` L53558ff), built from `assignments` only. */
671
+ interface ShareAttachmentIndex {
672
+ readonly agencyDefaults: Readonly<Record<string, string>>;
673
+ readonly internalDefaults: Readonly<Record<string, string>>;
674
+ readonly relationships: Readonly<Record<string, Readonly<Record<string, string>>>>;
675
+ readonly teamRows: Readonly<Record<string, Readonly<Record<string, string>>>>;
676
+ readonly teams: Readonly<Record<string, Readonly<Record<string, string>>>>;
677
+ }
678
+ declare function attachmentIndexFromPolicies(policies: readonly SharePolicyDoc[] | null | undefined): ShareAttachmentIndex;
679
+ /** A team-to-team row as the account stores it (data.js `teamRows` / `teamPairs`, L53493-L53514). */
680
+ interface ShareTeamRowLike {
681
+ readonly id: string;
682
+ readonly myTeamId?: string | null;
683
+ readonly their?: {
684
+ readonly type?: string;
685
+ readonly id?: string;
686
+ } | null;
687
+ }
688
+ /**
689
+ * The row the first rung reads (data.js `internalPairRow` / `partnerTeamRow`,
690
+ * L53493-L53514). `rows` is ONE store, as the prototype keeps them: for a
691
+ * sibling team, the account's internal pairs (`policies.teamPairs`); for a
692
+ * partner, THAT partner's team rows (`partnerOverrides[partner].teamRows`, or
693
+ * the seeded rows) — never a flat list across partners. A sibling team's row
694
+ * is the one whose `their` is that team (direction matters — the sender
695
+ * first); a partner's row under a team-scoped relationship is the team's
696
+ * FIRST row, under an all-teams relationship the row whose `their` is absent,
697
+ * not a team, or this very partner. Rows that carry only share-back
698
+ * (answers-received) policies are dropped first. An external recipient has
699
+ * no row.
700
+ */
701
+ declare function matchTeamRow(rows: readonly ShareTeamRowLike[] | null | undefined, teamId: string | null | undefined, recipient: ShareRecipient, options?: {
702
+ readonly scopeMode?: "team_scoped" | "all_teams";
703
+ readonly shareBackOnlyRowIds?: readonly string[];
704
+ }): string | null;
705
+ /**
706
+ * Derive one purpose's Platform default as the four states (data.js
707
+ * `starterDerivedState` L53708 + `platformStarterScope` L53719ff),
708
+ * for every live CATEGORY of the tree, in this order — the first rule wins:
709
+ * System metadata → `always`; a category the platform requires for the
710
+ * purpose → `always`; off-by-default (heightened) → `never`; the seed list
711
+ * covers it (itself, an ancestor, or any row of it) → `default_on`, else
712
+ * `default_off`. An explicit bound overrides it for every category but
713
+ * `system`. `raw` is the starting scope: the seed's codes whose category is
714
+ * not Blocked or bound off, plus every bound-on and Required category, plus
715
+ * `system`.
716
+ */
717
+ declare function derivePlatformDefault(scope: SharingCeilingScope, purpose: string, seedList: readonly string[] | null | undefined, options?: {
718
+ readonly bounds?: Readonly<Record<string, SharePlatformState>> | null;
719
+ readonly required?: readonly string[] | null;
720
+ readonly version?: number | string;
721
+ readonly edited?: boolean;
722
+ }): SharePlatformDefault;
723
+ /** The live categories of the tree, in tree order. */
724
+ declare function liveCategories(scope: SharingCeilingScope): string[];
725
+ /** The System-metadata category (`system`, the parent of `system_info`). */
726
+ declare function systemCategoryOf(scope: SharingCeilingScope): string | undefined;
727
+ /**
728
+ * The categories the platform REQUIRES for a purpose (data.js `scopeRequiredByPurpose`,
729
+ * L40836-L40839): Identifying information on every report. Read by `platformDefaultFor`.
730
+ */
731
+ declare const HTI_SHARE_PLATFORM_REQUIRED_BY_PURPOSE: Readonly<Record<string, readonly string[]>>;
732
+ /**
733
+ * The Platform default for one purpose from the PUBLISHED starter (the day-one tier document,
734
+ * version 1, no bounds): `derivePlatformDefault` over `HTI_SHARE_PLATFORM_STARTER.scopeByPurpose`
735
+ * and {@link HTI_SHARE_PLATFORM_REQUIRED_BY_PURPOSE}. `null` for a purpose the starter has no row
736
+ * for (the resolver then fails closed). Once the platform stores `pol-starter-<purpose>` as a
737
+ * versioned document, pass ITS list, bounds and version instead.
738
+ */
739
+ declare function platformDefaultFor(scope: SharingCeilingScope, purpose: string, options?: {
740
+ readonly starter?: SharingPlatformStarter;
741
+ readonly bounds?: Readonly<Record<string, SharePlatformState>> | null;
742
+ readonly version?: number | string;
743
+ readonly edited?: boolean;
744
+ }): SharePlatformDefault | null;
745
+ /**
746
+ * The ROW-grain ceiling one resolution amounts to — the list the item-grain readers take
747
+ * (`maskSelectionToCeiling` for the composer, `rowsOverCeiling` for the send door): each
748
+ * allowed category by its own code when no row of it is withheld, else its live rows minus
749
+ * the withheld ones (the governing list's, the account's heightened rows, the field-group
750
+ * limits, the team's). Rows under the platform floor are never listed (the readers never let
751
+ * them through). `[]` for an excluded share — only System metadata rides.
752
+ */
753
+ declare function shareRowCeiling(resolution: Pick<ShareResolution, "allowed" | "scope" | "allowedCategories">, scope: SharingCeilingScope): string[];
754
+ /**
755
+ * THE read. See the module header; the algorithm, step by step:
756
+ * 1. the ladder (`governingPolicyFor`): pair row → [inside: the account's
757
+ * inside default → the platform's inside starter, stop] → relationship
758
+ * (the partner id, or `__external__`) → the account default → the
759
+ * Platform default (a versioned document, `pol-starter-<purpose>`);
760
+ * 2. the sending team's own policy for the purpose rides as a CEILING when
761
+ * it is not the governing one (inside the account too);
762
+ * 3. posture: the relationship's, raised (never lowered) by the governing
763
+ * policy, then by the ceiling — stricter wins;
764
+ * 4. the whole share: the purpose switch excludes it (reports too); a
765
+ * `blocked` posture excludes a discretionary share and CARVES OUT a
766
+ * report (never blocked at the policy / partner layer);
767
+ * 5. per category: Required (`system`, or the Platform default's `always`)
768
+ * bypasses every account-grain clamp; else the account's toggle (4), the
769
+ * Platform default's Blocked (4a, not inside), the binding list (5: the
770
+ * legacy cell chain's list or the Platform default's starting scope — the
771
+ * governing policy's own list when it is authored (5b); K13-12), the
772
+ * team ceiling's list (5d); rows: the floor, heightened rows off (4b),
773
+ * field-group limits (5c), and a category every row of which is withheld
774
+ * is withheld (the group flip).
775
+ */
776
+ declare function resolveShare(input: ShareResolveInput): ShareResolution;
317
777
 
318
- export { type EffectiveSharingCeiling, type EffectiveSharingCeilingInputs, HTI_SHARE_PLATFORM_PURPOSE_ENABLED, HTI_SHARE_PLATFORM_STARTER, HTI_SHARE_PLATFORM_STARTER_SOURCE, INFORMATION_SCOPE_FIELD_HOME_ROWS, SHARING_CEILING_DEFAULT_ROW_KEY, SHARING_CEILING_EXTERNAL_ROW_KEY, SHARING_CEILING_SCOPE_VERSION, type SharingCeilingAllowed, type SharingCeilingCellLike, type SharingCeilingRung, type SharingCeilingScope, type SharingPlatformStarter, type SharingPurposeLists, type SharingScopeEdits, ceilingCoverage, effectiveCeiling, hasOwnScopeContent, isCeilingCoverageRow, isSharingPurposeDisabled, maskSelectionToCeiling, rowsExpandedByCeiling, rowsOutsideCeiling, rowsOverCeiling, scopeRowWithinCeiling, sharingCeilingCellList, sharingCeilingRowKey, sharingScopeEditsFromCells };
778
+ 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 };