@htilabs/platform-common-models 0.21.0 → 0.23.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 (71) hide show
  1. package/dist/authz/index.cjs +539 -0
  2. package/dist/authz/index.cjs.map +1 -0
  3. package/dist/authz/index.d.cts +210 -0
  4. package/dist/authz/index.d.ts +210 -0
  5. package/dist/authz/index.js +507 -0
  6. package/dist/authz/index.js.map +1 -0
  7. package/dist/constants/index.d.cts +2 -1
  8. package/dist/constants/index.d.ts +2 -1
  9. package/dist/cvcs/index.cjs +936 -243
  10. package/dist/cvcs/index.cjs.map +1 -1
  11. package/dist/cvcs/index.d.cts +986 -254
  12. package/dist/cvcs/index.d.ts +986 -254
  13. package/dist/cvcs/index.js +936 -243
  14. package/dist/cvcs/index.js.map +1 -1
  15. package/dist/enums/index.cjs +37 -10
  16. package/dist/enums/index.cjs.map +1 -1
  17. package/dist/enums/index.d.cts +42 -15
  18. package/dist/enums/index.d.ts +42 -15
  19. package/dist/enums/index.js +37 -10
  20. package/dist/enums/index.js.map +1 -1
  21. package/dist/{platform-auth-CvAYFVhK.d.cts → ic-DpKrdgQP.d.cts} +1 -78
  22. package/dist/{platform-auth-CvAYFVhK.d.ts → ic-DpKrdgQP.d.ts} +1 -78
  23. package/dist/index.cjs +1328 -253
  24. package/dist/index.cjs.map +1 -1
  25. package/dist/index.d.cts +4 -2
  26. package/dist/index.d.ts +4 -2
  27. package/dist/index.js +1313 -253
  28. package/dist/index.js.map +1 -1
  29. package/dist/platform-auth-B49Ly57B.d.cts +78 -0
  30. package/dist/platform-auth-B49Ly57B.d.ts +78 -0
  31. package/dist/schemas/index.cjs +104 -0
  32. package/dist/schemas/index.cjs.map +1 -1
  33. package/dist/schemas/index.d.cts +240 -1
  34. package/dist/schemas/index.d.ts +240 -1
  35. package/dist/schemas/index.js +95 -0
  36. package/dist/schemas/index.js.map +1 -1
  37. package/dist/types/index.d.cts +2 -2
  38. package/dist/types/index.d.ts +2 -2
  39. package/package.json +6 -1
  40. package/src/__sot__/README.md +3 -0
  41. package/src/__sot__/adminRoles.pin.json +122 -0
  42. package/src/__sot__/adminRoles.published.json +77 -0
  43. package/src/__sot__/coreFunctionFields.ts +137 -0
  44. package/src/__sot__/coreFunctions.pin.json +1659 -0
  45. package/src/__sot__/coreFunctions.published.json +233 -0
  46. package/src/__sot__/roleFields.ts +137 -0
  47. package/src/__sot__/userRoles.pin.json +174 -0
  48. package/src/__sot__/userRoles.published.json +103 -0
  49. package/src/__tests__/__snapshots__/cvc-sot.snap +6 -6
  50. package/src/__tests__/admin-roles-canon.test.ts +80 -0
  51. package/src/__tests__/authz-resolve.test.ts +712 -0
  52. package/src/__tests__/core-functions-canon.test.ts +358 -24
  53. package/src/__tests__/cvc-sot-snapshot.test.ts +17 -6
  54. package/src/__tests__/cvc-status-parser.test.ts +2 -2
  55. package/src/__tests__/cvc-structural.test.ts +3 -3
  56. package/src/__tests__/organization-program.test.ts +254 -0
  57. package/src/__tests__/role-vocab-gate.ts +279 -0
  58. package/src/__tests__/user-roles-canon.test.ts +104 -0
  59. package/src/authz/index.ts +9 -0
  60. package/src/authz/resolveEffectiveFunctions.ts +454 -0
  61. package/src/cvcs/adminRoles.v2.0.0.json +197 -0
  62. package/src/cvcs/{coreFunctions.v1.1.0.json → coreFunctions.v1.3.0.json} +646 -90
  63. package/src/cvcs/index.ts +3 -3
  64. package/src/cvcs/userRoles.v2.0.0.json +296 -0
  65. package/src/generated/coreFunctionsEvaluable.ts +101 -0
  66. package/src/generated/cvc-enums.ts +42 -15
  67. package/src/index.ts +4 -0
  68. package/src/schemas/index.ts +18 -0
  69. package/src/schemas/organization-program.ts +297 -0
  70. package/src/cvcs/adminRoles.v1.0.0.json +0 -153
  71. package/src/cvcs/userRoles.v1.0.0.json +0 -203
@@ -420,4 +420,243 @@ declare function addTeamDirectoryFields<S extends Schema>(schema: S): S;
420
420
  */
421
421
  type TeamDirectoryFields = Partial<InferRawDocType<typeof teamDirectorySchemaDefinition>>;
422
422
 
423
- export { type Address, type Demographics, type Email, type PersonName, type Phone, TEAM_MODEL_NAME, type TeamDirectoryFields, addTeamDirectoryFields, addressSchema, demographicsSchema, emailSchema, personNameSchema, phoneSchema, teamDirectorySchemaDefinition };
423
+ /**
424
+ * @htilabs/platform-common-models — Organization program rows (`organizations.programs[]`)
425
+ *
426
+ * The ONE definition of the embedded program sub-document on the platform-db
427
+ * `organizations` collection, which both apps read and PAVE 2.0 writes.
428
+ *
429
+ * ## This is a FRAGMENT, not an Organization model
430
+ *
431
+ * No canonical Organization schema exists in this package (same posture as
432
+ * `schemas/team.ts` and `schemas/agency.ts`). `organizations` is written by
433
+ * PAVE 2.0 (`packages/db/src/models/organization.ts`) and read by Thread
434
+ * (`packages/db/src/models/platform/Organization.ts`, `select: false` on
435
+ * `programs`, read with `+programs`). Until this module, each app carried its
436
+ * own copy of the sub-schema — identical by hand. This module declares the
437
+ * program row ONCE; each consumer mounts it with
438
+ * {@link addOrganizationProgramsField} or builds the sub-schema with
439
+ * {@link buildOrganizationProgramSchema}.
440
+ *
441
+ * ## Canon
442
+ *
443
+ * - **UDD Program Data Object** (hti-features `udd-schemas/program/Program.v1.json`;
444
+ * profile confirmed by Crysta 2026-10-05): a Program (program / department /
445
+ * operational division / law-enforcement unit) is a fact about an
446
+ * ORGANIZATION — `org_id` is the owner. Its arrival is stored: `added_by`,
447
+ * `added_in_app`, `review_status`.
448
+ * - **PROGRAM-APP-ADDED** (prototype 2026-10-06; Crysta 2026-10-02: users
449
+ * "need to be able to capture org names and program names that may not be
450
+ * in existing list"): a program named inside an app is the organization's
451
+ * program from the moment it is typed, and waits for HTI Labs' review like a
452
+ * new organization does (GDR § 5.12 / § 5.16 rule 1). The steward's review
453
+ * queue in the HTI Platform confirms or rejects it; a confirmed row's "new"
454
+ * mark clears.
455
+ * - **ADR D13** (PAVE Greenfield): `SharingSettings` keys on
456
+ * `(organizationId, programId?)` — the program id is the join key an
457
+ * agency may share to.
458
+ *
459
+ * ## Field names
460
+ *
461
+ * Canon's program sheet spells these `program_id`, `label`, `review_status`,
462
+ * `added_by`, `added_in_app` (snake_case CSV columns). The live platform-db
463
+ * writers use camelCase (`programId`, `name`, `defaultSharingPolicy` are what
464
+ * PAVE 2.0 and Thread already store), so the arrival fields follow that
465
+ * convention: `reviewStatus`, `addedBy`, `addedInApp`, `addedInSession`.
466
+ *
467
+ * `addedInApp` is where the program was NAMED, not the program's own app
468
+ * (which app it operates in stays blank until the Admin Hub says).
469
+ *
470
+ * `addedInSession` is NOT on the UDD Program sheet (`Program.v1.json` carries
471
+ * `review_status · added_by · added_in_app` only). It is carried on the same
472
+ * precedent as the Org object's `added_in_session` (as-built OrgEntry overlay;
473
+ * RULED 2026-08-27 a migration note that retires into the `dataSource`
474
+ * provenance envelope at the cut-over) so a picker can tell "named in THIS
475
+ * session" from "awaiting review" across a reload. It retires with that trio.
476
+ *
477
+ * The sub-schema is STRICT (Mongoose default): a key outside the definition
478
+ * — including the sheet's snake_case spellings (`review_status`,
479
+ * `added_by`) — is dropped silently on cast, not rejected. Write camelCase.
480
+ *
481
+ * ## Who dedupes
482
+ *
483
+ * `programId` uniqueness and name-matching on add are the WRITER's job; the
484
+ * fragment enforces neither (two rows with one id validate and `$push`).
485
+ * PAVE 2.0's `POST /organizations/:id/programs` dedupes a typed name against
486
+ * the live rows (trimmed, case-insensitive) and mints `programId` server-side.
487
+ *
488
+ * ## Missingness
489
+ *
490
+ * `reviewStatus` is ABSENT (or null) on a steward row — nothing to review.
491
+ * There is no UNK / ANON / DNC here: the status is a lifecycle, not an
492
+ * answer anyone gives.
493
+ */
494
+
495
+ /**
496
+ * Review lifecycle of a program named inside an app (UDD Program
497
+ * `review_status`). The sheet's own words — a lane's `pending_steward` /
498
+ * `declined` never reach the stored row.
499
+ */
500
+ declare const PROGRAM_REVIEW_STATUS: {
501
+ readonly PENDING: "pending";
502
+ readonly CONFIRMED: "confirmed";
503
+ readonly REJECTED: "rejected";
504
+ };
505
+ type ProgramReviewStatus = (typeof PROGRAM_REVIEW_STATUS)[keyof typeof PROGRAM_REVIEW_STATUS];
506
+ /** The three values, for `enum:` declarations and Zod `z.enum`. */
507
+ declare const PROGRAM_REVIEW_STATUS_VALUES: readonly ["pending", "confirmed", "rejected"];
508
+ declare function isProgramReviewStatus(value: unknown): value is ProgramReviewStatus;
509
+ /**
510
+ * One embedded Organization > Program row. `programId` + `name` are the
511
+ * load-bearing identity/label; everything else is optional and additive.
512
+ *
513
+ * `status` and `defaultSharingPolicy` are typed string codes (as PAVE 2.0 and
514
+ * Thread already store them — the CVC bind is a follow-up on the codebook,
515
+ * not this fragment).
516
+ */
517
+ declare const organizationProgramSchemaDefinition: {
518
+ /** Stable identifier for the program within its Organization (server-minted). */
519
+ readonly programId: {
520
+ readonly type: StringConstructor;
521
+ readonly required: true;
522
+ };
523
+ /** Human-facing program name (canon `label`). */
524
+ readonly name: {
525
+ readonly type: StringConstructor;
526
+ readonly required: true;
527
+ };
528
+ /** Free-text program description. */
529
+ readonly description: {
530
+ readonly type: StringConstructor;
531
+ readonly required: false;
532
+ };
533
+ /** Lifecycle code; a `retired` program is not offered to pickers. */
534
+ readonly status: {
535
+ readonly type: StringConstructor;
536
+ readonly required: false;
537
+ };
538
+ /** Default sharing-policy code applied when sharing to this program (ADR D13). */
539
+ readonly defaultSharingPolicy: {
540
+ readonly type: StringConstructor;
541
+ readonly required: false;
542
+ };
543
+ /**
544
+ * pending · confirmed · rejected for a program named inside an app; absent on
545
+ * a steward row. A `rejected` row is never offered and never captures its
546
+ * name on a later add (a new row is minted).
547
+ */
548
+ readonly reviewStatus: {
549
+ readonly type: StringConstructor;
550
+ readonly required: false;
551
+ readonly enum: readonly ["pending", "confirmed", "rejected"];
552
+ };
553
+ /** The seat (user id) that named it inside an app. */
554
+ readonly addedBy: {
555
+ readonly type: StringConstructor;
556
+ readonly required: false;
557
+ };
558
+ /** The app it was NAMED in (`pave` · `thread` · `leads` · `platform`). */
559
+ readonly addedInApp: {
560
+ readonly type: StringConstructor;
561
+ readonly required: false;
562
+ };
563
+ /** The session it was named in, when there was one. */
564
+ readonly addedInSession: {
565
+ readonly type: StringConstructor;
566
+ readonly required: false;
567
+ };
568
+ };
569
+ /**
570
+ * Build the program sub-schema. `{ _id: false }` — a program is identified by
571
+ * its own `programId`, not a Mongoose ObjectId (as both apps already do).
572
+ */
573
+ declare function buildOrganizationProgramSchema(): Schema;
574
+ /**
575
+ * Build the `programs` field to add to an organization schema — a FRESH
576
+ * sub-schema per call. Mongoose does not clone a `Schema` instance on
577
+ * `schema.add()` or embedding, so a module-level instance would be shared by
578
+ * every consumer: a pre-hook, virtual or index one consumer put on its rows
579
+ * would run on, or be created for, every other consumer's documents (review
580
+ * finding, 2026-10-12). Each mount gets its own instance.
581
+ *
582
+ * `default: undefined` (NOT Mongoose's implicit `[]` for array paths): an
583
+ * organization without programs persists nothing and round-trips as absent,
584
+ * which keeps "none declared" distinct from "declared empty" and leaves every
585
+ * existing document's shape untouched.
586
+ */
587
+ declare function buildOrganizationProgramsFieldDefinition(): {
588
+ programs: {
589
+ type: Schema[];
590
+ required: false;
591
+ default: undefined;
592
+ };
593
+ };
594
+ /**
595
+ * Update operations on which the row validators (enum, `required`) are
596
+ * enforced by {@link addOrganizationProgramsField}. Mongoose skips validators
597
+ * on update operations by default, and `$push` of a program row is the write
598
+ * path this fragment exists for (PAVE's `POST /organizations/:id/programs`).
599
+ */
600
+ declare const ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS: readonly ["updateOne", "updateMany", "findOneAndUpdate"];
601
+ interface AddOrganizationProgramsFieldOptions {
602
+ /** The path's `select` option; `false` is Thread's read posture. Omitted → Mongoose default. */
603
+ select?: boolean;
604
+ /**
605
+ * Install a `pre` hook on {@link ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS}
606
+ * that turns `runValidators` on unless the caller set it, so a `$push` of a
607
+ * row with a review status outside the vocabulary, or with no `programId`,
608
+ * is refused on the update paths exactly as on `save()` (the `agency.ts`
609
+ * precedent). Default `true`.
610
+ *
611
+ * SCHEMA-WIDE on these ops, not just `programs`: once mounted, every
612
+ * `updateOne` / `updateMany` / `findOneAndUpdate` on the consumer's schema
613
+ * runs validators for EVERY path it touches, unless the caller passes
614
+ * `runValidators` explicitly. A consumer that relied on Mongoose's default of
615
+ * skipping validators on updates for its other fields will see new
616
+ * rejections after mounting this. Pass `{ validateOnUpdate: false }` to opt
617
+ * out, or set `runValidators: false` on an individual query.
618
+ */
619
+ validateOnUpdate?: boolean;
620
+ }
621
+ /**
622
+ * Add the `programs[]` field to an existing organization schema.
623
+ *
624
+ * Adds no indexes. Installs the update-path validation hook described on
625
+ * {@link AddOrganizationProgramsFieldOptions} unless opted out. A consumer
626
+ * that wants `select: false` on the field (Thread) passes `{ select: false }`.
627
+ *
628
+ * REPLACES a `programs` path the consumer already declares (`schema.add`
629
+ * overwrites the path wholesale — the consumer's own sub-fields and its own
630
+ * `select` option do not survive). That is the point of ONE definition: a
631
+ * consumer removes its local `programs` declaration and passes its read
632
+ * posture here instead. A `console.warn` names the overwrite so a consumer
633
+ * that forgot does not lose `select: false` silently.
634
+ *
635
+ * @param schema - The consumer's organization schema
636
+ * @returns The same schema, for chaining
637
+ */
638
+ declare function addOrganizationProgramsField<S extends Schema>(schema: S, options?: AddOrganizationProgramsFieldOptions): S;
639
+ /**
640
+ * Whether a program row may be OFFERED (and matched by name on an add).
641
+ * A retired or rejected program is not a place anyone can be enrolled today,
642
+ * so pickers do not list it and typing its name mints a new row rather than
643
+ * binding to it (the prototype's independent pre-review catch, 2026-10-06).
644
+ */
645
+ declare function isLiveOrganizationProgram(row: {
646
+ status?: string | null | undefined;
647
+ reviewStatus?: string | null | undefined;
648
+ }): boolean;
649
+ /**
650
+ * Raw (persistence) shape of one program row, inferred from the DEFINITION.
651
+ *
652
+ * `programId` + `name` are required; every other field is optional (and may
653
+ * be `null`); `reviewStatus` is the three-word union. `{ _id: false }` matches
654
+ * the sub-schema, so the type carries no `_id` (the definition is `as const`
655
+ * so `required: false` stays a literal and is honoured by the inference).
656
+ */
657
+ type OrganizationProgram = InferRawDocType<typeof organizationProgramSchemaDefinition, {
658
+ _id: false;
659
+ typeKey: "type";
660
+ }>;
661
+
662
+ export { type AddOrganizationProgramsFieldOptions, type Address, type Demographics, type Email, ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS, type OrganizationProgram, PROGRAM_REVIEW_STATUS, PROGRAM_REVIEW_STATUS_VALUES, type PersonName, type Phone, type ProgramReviewStatus, TEAM_MODEL_NAME, type TeamDirectoryFields, addOrganizationProgramsField, addTeamDirectoryFields, addressSchema, buildOrganizationProgramSchema, buildOrganizationProgramsFieldDefinition, demographicsSchema, emailSchema, isLiveOrganizationProgram, isProgramReviewStatus, organizationProgramSchemaDefinition, personNameSchema, phoneSchema, teamDirectorySchemaDefinition };
@@ -420,4 +420,243 @@ declare function addTeamDirectoryFields<S extends Schema>(schema: S): S;
420
420
  */
421
421
  type TeamDirectoryFields = Partial<InferRawDocType<typeof teamDirectorySchemaDefinition>>;
422
422
 
423
- export { type Address, type Demographics, type Email, type PersonName, type Phone, TEAM_MODEL_NAME, type TeamDirectoryFields, addTeamDirectoryFields, addressSchema, demographicsSchema, emailSchema, personNameSchema, phoneSchema, teamDirectorySchemaDefinition };
423
+ /**
424
+ * @htilabs/platform-common-models — Organization program rows (`organizations.programs[]`)
425
+ *
426
+ * The ONE definition of the embedded program sub-document on the platform-db
427
+ * `organizations` collection, which both apps read and PAVE 2.0 writes.
428
+ *
429
+ * ## This is a FRAGMENT, not an Organization model
430
+ *
431
+ * No canonical Organization schema exists in this package (same posture as
432
+ * `schemas/team.ts` and `schemas/agency.ts`). `organizations` is written by
433
+ * PAVE 2.0 (`packages/db/src/models/organization.ts`) and read by Thread
434
+ * (`packages/db/src/models/platform/Organization.ts`, `select: false` on
435
+ * `programs`, read with `+programs`). Until this module, each app carried its
436
+ * own copy of the sub-schema — identical by hand. This module declares the
437
+ * program row ONCE; each consumer mounts it with
438
+ * {@link addOrganizationProgramsField} or builds the sub-schema with
439
+ * {@link buildOrganizationProgramSchema}.
440
+ *
441
+ * ## Canon
442
+ *
443
+ * - **UDD Program Data Object** (hti-features `udd-schemas/program/Program.v1.json`;
444
+ * profile confirmed by Crysta 2026-10-05): a Program (program / department /
445
+ * operational division / law-enforcement unit) is a fact about an
446
+ * ORGANIZATION — `org_id` is the owner. Its arrival is stored: `added_by`,
447
+ * `added_in_app`, `review_status`.
448
+ * - **PROGRAM-APP-ADDED** (prototype 2026-10-06; Crysta 2026-10-02: users
449
+ * "need to be able to capture org names and program names that may not be
450
+ * in existing list"): a program named inside an app is the organization's
451
+ * program from the moment it is typed, and waits for HTI Labs' review like a
452
+ * new organization does (GDR § 5.12 / § 5.16 rule 1). The steward's review
453
+ * queue in the HTI Platform confirms or rejects it; a confirmed row's "new"
454
+ * mark clears.
455
+ * - **ADR D13** (PAVE Greenfield): `SharingSettings` keys on
456
+ * `(organizationId, programId?)` — the program id is the join key an
457
+ * agency may share to.
458
+ *
459
+ * ## Field names
460
+ *
461
+ * Canon's program sheet spells these `program_id`, `label`, `review_status`,
462
+ * `added_by`, `added_in_app` (snake_case CSV columns). The live platform-db
463
+ * writers use camelCase (`programId`, `name`, `defaultSharingPolicy` are what
464
+ * PAVE 2.0 and Thread already store), so the arrival fields follow that
465
+ * convention: `reviewStatus`, `addedBy`, `addedInApp`, `addedInSession`.
466
+ *
467
+ * `addedInApp` is where the program was NAMED, not the program's own app
468
+ * (which app it operates in stays blank until the Admin Hub says).
469
+ *
470
+ * `addedInSession` is NOT on the UDD Program sheet (`Program.v1.json` carries
471
+ * `review_status · added_by · added_in_app` only). It is carried on the same
472
+ * precedent as the Org object's `added_in_session` (as-built OrgEntry overlay;
473
+ * RULED 2026-08-27 a migration note that retires into the `dataSource`
474
+ * provenance envelope at the cut-over) so a picker can tell "named in THIS
475
+ * session" from "awaiting review" across a reload. It retires with that trio.
476
+ *
477
+ * The sub-schema is STRICT (Mongoose default): a key outside the definition
478
+ * — including the sheet's snake_case spellings (`review_status`,
479
+ * `added_by`) — is dropped silently on cast, not rejected. Write camelCase.
480
+ *
481
+ * ## Who dedupes
482
+ *
483
+ * `programId` uniqueness and name-matching on add are the WRITER's job; the
484
+ * fragment enforces neither (two rows with one id validate and `$push`).
485
+ * PAVE 2.0's `POST /organizations/:id/programs` dedupes a typed name against
486
+ * the live rows (trimmed, case-insensitive) and mints `programId` server-side.
487
+ *
488
+ * ## Missingness
489
+ *
490
+ * `reviewStatus` is ABSENT (or null) on a steward row — nothing to review.
491
+ * There is no UNK / ANON / DNC here: the status is a lifecycle, not an
492
+ * answer anyone gives.
493
+ */
494
+
495
+ /**
496
+ * Review lifecycle of a program named inside an app (UDD Program
497
+ * `review_status`). The sheet's own words — a lane's `pending_steward` /
498
+ * `declined` never reach the stored row.
499
+ */
500
+ declare const PROGRAM_REVIEW_STATUS: {
501
+ readonly PENDING: "pending";
502
+ readonly CONFIRMED: "confirmed";
503
+ readonly REJECTED: "rejected";
504
+ };
505
+ type ProgramReviewStatus = (typeof PROGRAM_REVIEW_STATUS)[keyof typeof PROGRAM_REVIEW_STATUS];
506
+ /** The three values, for `enum:` declarations and Zod `z.enum`. */
507
+ declare const PROGRAM_REVIEW_STATUS_VALUES: readonly ["pending", "confirmed", "rejected"];
508
+ declare function isProgramReviewStatus(value: unknown): value is ProgramReviewStatus;
509
+ /**
510
+ * One embedded Organization > Program row. `programId` + `name` are the
511
+ * load-bearing identity/label; everything else is optional and additive.
512
+ *
513
+ * `status` and `defaultSharingPolicy` are typed string codes (as PAVE 2.0 and
514
+ * Thread already store them — the CVC bind is a follow-up on the codebook,
515
+ * not this fragment).
516
+ */
517
+ declare const organizationProgramSchemaDefinition: {
518
+ /** Stable identifier for the program within its Organization (server-minted). */
519
+ readonly programId: {
520
+ readonly type: StringConstructor;
521
+ readonly required: true;
522
+ };
523
+ /** Human-facing program name (canon `label`). */
524
+ readonly name: {
525
+ readonly type: StringConstructor;
526
+ readonly required: true;
527
+ };
528
+ /** Free-text program description. */
529
+ readonly description: {
530
+ readonly type: StringConstructor;
531
+ readonly required: false;
532
+ };
533
+ /** Lifecycle code; a `retired` program is not offered to pickers. */
534
+ readonly status: {
535
+ readonly type: StringConstructor;
536
+ readonly required: false;
537
+ };
538
+ /** Default sharing-policy code applied when sharing to this program (ADR D13). */
539
+ readonly defaultSharingPolicy: {
540
+ readonly type: StringConstructor;
541
+ readonly required: false;
542
+ };
543
+ /**
544
+ * pending · confirmed · rejected for a program named inside an app; absent on
545
+ * a steward row. A `rejected` row is never offered and never captures its
546
+ * name on a later add (a new row is minted).
547
+ */
548
+ readonly reviewStatus: {
549
+ readonly type: StringConstructor;
550
+ readonly required: false;
551
+ readonly enum: readonly ["pending", "confirmed", "rejected"];
552
+ };
553
+ /** The seat (user id) that named it inside an app. */
554
+ readonly addedBy: {
555
+ readonly type: StringConstructor;
556
+ readonly required: false;
557
+ };
558
+ /** The app it was NAMED in (`pave` · `thread` · `leads` · `platform`). */
559
+ readonly addedInApp: {
560
+ readonly type: StringConstructor;
561
+ readonly required: false;
562
+ };
563
+ /** The session it was named in, when there was one. */
564
+ readonly addedInSession: {
565
+ readonly type: StringConstructor;
566
+ readonly required: false;
567
+ };
568
+ };
569
+ /**
570
+ * Build the program sub-schema. `{ _id: false }` — a program is identified by
571
+ * its own `programId`, not a Mongoose ObjectId (as both apps already do).
572
+ */
573
+ declare function buildOrganizationProgramSchema(): Schema;
574
+ /**
575
+ * Build the `programs` field to add to an organization schema — a FRESH
576
+ * sub-schema per call. Mongoose does not clone a `Schema` instance on
577
+ * `schema.add()` or embedding, so a module-level instance would be shared by
578
+ * every consumer: a pre-hook, virtual or index one consumer put on its rows
579
+ * would run on, or be created for, every other consumer's documents (review
580
+ * finding, 2026-10-12). Each mount gets its own instance.
581
+ *
582
+ * `default: undefined` (NOT Mongoose's implicit `[]` for array paths): an
583
+ * organization without programs persists nothing and round-trips as absent,
584
+ * which keeps "none declared" distinct from "declared empty" and leaves every
585
+ * existing document's shape untouched.
586
+ */
587
+ declare function buildOrganizationProgramsFieldDefinition(): {
588
+ programs: {
589
+ type: Schema[];
590
+ required: false;
591
+ default: undefined;
592
+ };
593
+ };
594
+ /**
595
+ * Update operations on which the row validators (enum, `required`) are
596
+ * enforced by {@link addOrganizationProgramsField}. Mongoose skips validators
597
+ * on update operations by default, and `$push` of a program row is the write
598
+ * path this fragment exists for (PAVE's `POST /organizations/:id/programs`).
599
+ */
600
+ declare const ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS: readonly ["updateOne", "updateMany", "findOneAndUpdate"];
601
+ interface AddOrganizationProgramsFieldOptions {
602
+ /** The path's `select` option; `false` is Thread's read posture. Omitted → Mongoose default. */
603
+ select?: boolean;
604
+ /**
605
+ * Install a `pre` hook on {@link ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS}
606
+ * that turns `runValidators` on unless the caller set it, so a `$push` of a
607
+ * row with a review status outside the vocabulary, or with no `programId`,
608
+ * is refused on the update paths exactly as on `save()` (the `agency.ts`
609
+ * precedent). Default `true`.
610
+ *
611
+ * SCHEMA-WIDE on these ops, not just `programs`: once mounted, every
612
+ * `updateOne` / `updateMany` / `findOneAndUpdate` on the consumer's schema
613
+ * runs validators for EVERY path it touches, unless the caller passes
614
+ * `runValidators` explicitly. A consumer that relied on Mongoose's default of
615
+ * skipping validators on updates for its other fields will see new
616
+ * rejections after mounting this. Pass `{ validateOnUpdate: false }` to opt
617
+ * out, or set `runValidators: false` on an individual query.
618
+ */
619
+ validateOnUpdate?: boolean;
620
+ }
621
+ /**
622
+ * Add the `programs[]` field to an existing organization schema.
623
+ *
624
+ * Adds no indexes. Installs the update-path validation hook described on
625
+ * {@link AddOrganizationProgramsFieldOptions} unless opted out. A consumer
626
+ * that wants `select: false` on the field (Thread) passes `{ select: false }`.
627
+ *
628
+ * REPLACES a `programs` path the consumer already declares (`schema.add`
629
+ * overwrites the path wholesale — the consumer's own sub-fields and its own
630
+ * `select` option do not survive). That is the point of ONE definition: a
631
+ * consumer removes its local `programs` declaration and passes its read
632
+ * posture here instead. A `console.warn` names the overwrite so a consumer
633
+ * that forgot does not lose `select: false` silently.
634
+ *
635
+ * @param schema - The consumer's organization schema
636
+ * @returns The same schema, for chaining
637
+ */
638
+ declare function addOrganizationProgramsField<S extends Schema>(schema: S, options?: AddOrganizationProgramsFieldOptions): S;
639
+ /**
640
+ * Whether a program row may be OFFERED (and matched by name on an add).
641
+ * A retired or rejected program is not a place anyone can be enrolled today,
642
+ * so pickers do not list it and typing its name mints a new row rather than
643
+ * binding to it (the prototype's independent pre-review catch, 2026-10-06).
644
+ */
645
+ declare function isLiveOrganizationProgram(row: {
646
+ status?: string | null | undefined;
647
+ reviewStatus?: string | null | undefined;
648
+ }): boolean;
649
+ /**
650
+ * Raw (persistence) shape of one program row, inferred from the DEFINITION.
651
+ *
652
+ * `programId` + `name` are required; every other field is optional (and may
653
+ * be `null`); `reviewStatus` is the three-word union. `{ _id: false }` matches
654
+ * the sub-schema, so the type carries no `_id` (the definition is `as const`
655
+ * so `required: false` stays a literal and is honoured by the inference).
656
+ */
657
+ type OrganizationProgram = InferRawDocType<typeof organizationProgramSchemaDefinition, {
658
+ _id: false;
659
+ typeKey: "type";
660
+ }>;
661
+
662
+ export { type AddOrganizationProgramsFieldOptions, type Address, type Demographics, type Email, ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS, type OrganizationProgram, PROGRAM_REVIEW_STATUS, PROGRAM_REVIEW_STATUS_VALUES, type PersonName, type Phone, type ProgramReviewStatus, TEAM_MODEL_NAME, type TeamDirectoryFields, addOrganizationProgramsField, addTeamDirectoryFields, addressSchema, buildOrganizationProgramSchema, buildOrganizationProgramsFieldDefinition, demographicsSchema, emailSchema, isLiveOrganizationProgram, isProgramReviewStatus, organizationProgramSchemaDefinition, personNameSchema, phoneSchema, teamDirectorySchemaDefinition };
@@ -5782,13 +5782,103 @@ function orgTypeFieldsDiffer(org, agency) {
5782
5782
  const b = pickOrgTypeFields(agency);
5783
5783
  return ORG_TYPE_FIELD_NAMES.filter((k) => a[k] !== b[k]);
5784
5784
  }
5785
+
5786
+ // src/schemas/organization-program.ts
5787
+ import { Schema as Schema11 } from "mongoose";
5788
+ var PROGRAM_REVIEW_STATUS = {
5789
+ PENDING: "pending",
5790
+ CONFIRMED: "confirmed",
5791
+ REJECTED: "rejected"
5792
+ };
5793
+ var PROGRAM_REVIEW_STATUS_VALUES = Object.freeze([
5794
+ PROGRAM_REVIEW_STATUS.PENDING,
5795
+ PROGRAM_REVIEW_STATUS.CONFIRMED,
5796
+ PROGRAM_REVIEW_STATUS.REJECTED
5797
+ ]);
5798
+ function isProgramReviewStatus(value) {
5799
+ return typeof value === "string" && PROGRAM_REVIEW_STATUS_VALUES.includes(value);
5800
+ }
5801
+ var organizationProgramSchemaDefinition = {
5802
+ /** Stable identifier for the program within its Organization (server-minted). */
5803
+ programId: { type: String, required: true },
5804
+ /** Human-facing program name (canon `label`). */
5805
+ name: { type: String, required: true },
5806
+ /** Free-text program description. */
5807
+ description: { type: String, required: false },
5808
+ /** Lifecycle code; a `retired` program is not offered to pickers. */
5809
+ status: { type: String, required: false },
5810
+ /** Default sharing-policy code applied when sharing to this program (ADR D13). */
5811
+ defaultSharingPolicy: { type: String, required: false },
5812
+ /**
5813
+ * pending · confirmed · rejected for a program named inside an app; absent on
5814
+ * a steward row. A `rejected` row is never offered and never captures its
5815
+ * name on a later add (a new row is minted).
5816
+ */
5817
+ reviewStatus: {
5818
+ type: String,
5819
+ required: false,
5820
+ enum: [...PROGRAM_REVIEW_STATUS_VALUES]
5821
+ },
5822
+ /** The seat (user id) that named it inside an app. */
5823
+ addedBy: { type: String, required: false },
5824
+ /** The app it was NAMED in (`pave` · `thread` · `leads` · `platform`). */
5825
+ addedInApp: { type: String, required: false },
5826
+ /** The session it was named in, when there was one. */
5827
+ addedInSession: { type: String, required: false }
5828
+ };
5829
+ function buildOrganizationProgramSchema() {
5830
+ return new Schema11(organizationProgramSchemaDefinition, { _id: false });
5831
+ }
5832
+ function buildOrganizationProgramsFieldDefinition() {
5833
+ return {
5834
+ programs: {
5835
+ type: [buildOrganizationProgramSchema()],
5836
+ required: false,
5837
+ default: void 0
5838
+ }
5839
+ };
5840
+ }
5841
+ var ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS = Object.freeze([
5842
+ "updateOne",
5843
+ "updateMany",
5844
+ "findOneAndUpdate"
5845
+ ]);
5846
+ function addOrganizationProgramsField(schema, options = {}) {
5847
+ if (schema.path("programs")) {
5848
+ console.warn(
5849
+ "[platform-common-models] addOrganizationProgramsField: replacing the schema's own `programs` path with the shared fragment; pass `{ select: false }` here if that is the consumer's read posture."
5850
+ );
5851
+ }
5852
+ schema.add({
5853
+ programs: {
5854
+ ...buildOrganizationProgramsFieldDefinition().programs,
5855
+ ...options.select !== void 0 ? { select: options.select } : {}
5856
+ }
5857
+ });
5858
+ if (options.validateOnUpdate ?? true) {
5859
+ schema.pre(
5860
+ [...ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS],
5861
+ function() {
5862
+ applyRunValidatorsIfUnset(this);
5863
+ }
5864
+ );
5865
+ }
5866
+ return schema;
5867
+ }
5868
+ function isLiveOrganizationProgram(row) {
5869
+ return row.status !== "retired" && row.reviewStatus !== PROGRAM_REVIEW_STATUS.REJECTED;
5870
+ }
5785
5871
  export {
5786
5872
  AGENCY_ORG_TYPE_VALIDATED_UPDATE_OPS,
5873
+ ORGANIZATION_PROGRAM_VALIDATED_UPDATE_OPS,
5787
5874
  ORG_TYPE_FIELD_NAMES,
5875
+ PROGRAM_REVIEW_STATUS,
5876
+ PROGRAM_REVIEW_STATUS_VALUES,
5788
5877
  TEAM_MODEL_NAME,
5789
5878
  VSP_TWO_STEP_ISSUE,
5790
5879
  addAgencyOrgTypeFields,
5791
5880
  addOrgTypeFields,
5881
+ addOrganizationProgramsField,
5792
5882
  addTeamDirectoryFields,
5793
5883
  addressSchema,
5794
5884
  agencyOrgTypeSchemaDefinition,
@@ -5796,6 +5886,8 @@ export {
5796
5886
  buildCvcEntrySchema,
5797
5887
  buildCvcRegistrySchema,
5798
5888
  buildFormSchema,
5889
+ buildOrganizationProgramSchema,
5890
+ buildOrganizationProgramsFieldDefinition,
5799
5891
  buildPlatformFunctionSchema,
5800
5892
  buildPlatformRoleSchema,
5801
5893
  buildQuestionSchema,
@@ -5812,10 +5904,13 @@ export {
5812
5904
  formSchemaOptions,
5813
5905
  formSectionRefSchema,
5814
5906
  guidanceSchema,
5907
+ isLiveOrganizationProgram,
5908
+ isProgramReviewStatus,
5815
5909
  layoutSchema,
5816
5910
  mirrorOrgTypeFields,
5817
5911
  orgTypeFieldsDiffer,
5818
5912
  orgTypeSchemaDefinition,
5913
+ organizationProgramSchemaDefinition,
5819
5914
  personNameSchema,
5820
5915
  phoneSchema,
5821
5916
  platformFunctionSchemaDefinition,