@wildo-ai/saas-models 1.1.4 → 1.1.6

package/dist/esm/guidance/progression-presentation.shared.schemas.d.ts

@@ -0,0 +1,71 @@
+/** ──────────────────────────────────────────────────────────────
+ * Progression — Presentation Vocabulary
+ *
+ * How much of a person's progression a surface SHOWS. Distinct from
+ * `progression-state.shared.schemas.ts`, which is what the product RECORDS, and from
+ * `milestone-definition.shared.schemas.ts`, which is what an application DECLARES.
+ * ────────────────────────────────────────────────────────────── */
+/**
+ * @wildo_source:part:start saas.models.progression-tracker-variant facet:layer:shared facet:family:progression facet:audience:app-developer
+ *
+ * How much progression one `ProgressionMilestoneTracker` mount shows — passed as its `variant` prop.
+ * Import from `@wildo-ai/saas-models`.
+ *
+ * Chosen PER MOUNT, because surfaces of one application want different amounts: a home dashboard
+ * wants a glance, an achievements screen wants the detail, a product still teaching its first task
+ * wants only the next thing to do. Every variant reads the same progression state and the same
+ * milestone definitions; they differ only in how much of it reaches the screen.
+ *
+ * These four are the common shapes, not a ceiling — but the tracker is composed by name, not
+ * resolved through the component registry, so there is no preset to swap. An application needing a
+ * shape none of them covers builds its own card from `useProgression()` (exported by
+ * `@wildo-ai/saas-frontend-lib`), which gives the same milestone definitions, per-scope state and
+ * points total the tracker renders from.
+ */
+export declare enum ProgressionTrackerVariant {
+    /**
+     * Overall progress and the milestones actually in reach — nothing else.
+     *
+     * No categories, no points, no per-milestone bars, and ACHIEVED milestones are not listed at all:
+     * the "5 of 8" line is the record of them. For a surface whose job is to get someone to the next
+     * action rather than to celebrate the last one. The smallest shape, and the right default for a
+     * product that is still teaching itself.
+     */
+    NEXT_ACTIONS = "next_actions",
+    /**
+     * A glance: overall progress, the points total, and the single next milestone.
+     *
+     * For a dashboard card sitting beside other cards, where progression is one of several things
+     * competing for the same screen. Pairs with a `DETAILED` mount on a dedicated view — this is the
+     * summary that links to it.
+     */
+    SUMMARY = "summary",
+    /**
+     * One list and ONE progress signal.
+     *
+     * Categories become plain section headings rather than separately measured units, so there is a
+     * single bar for the whole surface; a per-milestone count appears only where one is genuinely in
+     * flight. Every milestone is listed, achieved ones included, with achievement carried by ONE
+     * encoding rather than four.
+     */
+    FLAT = "flat",
+    /**
+     * Categories measured in their own right, with the full per-milestone breakdown.
+     *
+     * The densest shape, for a screen whose whole subject is progression. It keeps the per-category
+     * bar and the per-milestone count that `FLAT` collapses, and gives them different visual weight so
+     * they stop competing — the defect in the original was never that both existed, it was that they
+     * were rendered identically and so read as one confused signal.
+     */
+    DETAILED = "detailed"
+}
+/**
+ * The shape used when a mount does not name one.
+ *
+ * `SUMMARY` rather than `DETAILED`, deliberately: the overwhelmingly common mount is a card on a
+ * home surface, and the density that made the original hard to read is exactly what a card cannot
+ * afford. An application that wants everything asks for it.
+ */
+export declare const DEFAULT_PROGRESSION_TRACKER_VARIANT: ProgressionTrackerVariant;
+/** @wildo_source:part:end saas.models.progression-tracker-variant */
+//# sourceMappingURL=progression-presentation.shared.schemas.d.ts.map

package/dist/esm/guidance/progression-presentation.shared.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progression-presentation.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/guidance/progression-presentation.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;oEAMoE;AAEpE;;;;;;;;;;;;;;;;GAgBG;AACH,oBAAY,yBAAyB;IACnC;;;;;;;OAOG;IACH,YAAY,iBAAiB;IAE7B;;;;;;OAMG;IACH,OAAO,YAAY;IAEnB;;;;;;;OAOG;IACH,IAAI,SAAS;IAEb;;;;;;;OAOG;IACH,QAAQ,aAAa;CACtB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mCAAmC,EAAE,yBAA6D,CAAC;AAChH,qEAAqE"}

package/dist/esm/guidance/progression-presentation.shared.schemas.js

@@ -0,0 +1,72 @@
+/** ──────────────────────────────────────────────────────────────
+ * Progression — Presentation Vocabulary
+ *
+ * How much of a person's progression a surface SHOWS. Distinct from
+ * `progression-state.shared.schemas.ts`, which is what the product RECORDS, and from
+ * `milestone-definition.shared.schemas.ts`, which is what an application DECLARES.
+ * ────────────────────────────────────────────────────────────── */
+/**
+ * @wildo_source:part:start saas.models.progression-tracker-variant facet:layer:shared facet:family:progression facet:audience:app-developer
+ *
+ * How much progression one `ProgressionMilestoneTracker` mount shows — passed as its `variant` prop.
+ * Import from `@wildo-ai/saas-models`.
+ *
+ * Chosen PER MOUNT, because surfaces of one application want different amounts: a home dashboard
+ * wants a glance, an achievements screen wants the detail, a product still teaching its first task
+ * wants only the next thing to do. Every variant reads the same progression state and the same
+ * milestone definitions; they differ only in how much of it reaches the screen.
+ *
+ * These four are the common shapes, not a ceiling — but the tracker is composed by name, not
+ * resolved through the component registry, so there is no preset to swap. An application needing a
+ * shape none of them covers builds its own card from `useProgression()` (exported by
+ * `@wildo-ai/saas-frontend-lib`), which gives the same milestone definitions, per-scope state and
+ * points total the tracker renders from.
+ */
+export var ProgressionTrackerVariant;
+(function (ProgressionTrackerVariant) {
+    /**
+     * Overall progress and the milestones actually in reach — nothing else.
+     *
+     * No categories, no points, no per-milestone bars, and ACHIEVED milestones are not listed at all:
+     * the "5 of 8" line is the record of them. For a surface whose job is to get someone to the next
+     * action rather than to celebrate the last one. The smallest shape, and the right default for a
+     * product that is still teaching itself.
+     */
+    ProgressionTrackerVariant["NEXT_ACTIONS"] = "next_actions";
+    /**
+     * A glance: overall progress, the points total, and the single next milestone.
+     *
+     * For a dashboard card sitting beside other cards, where progression is one of several things
+     * competing for the same screen. Pairs with a `DETAILED` mount on a dedicated view — this is the
+     * summary that links to it.
+     */
+    ProgressionTrackerVariant["SUMMARY"] = "summary";
+    /**
+     * One list and ONE progress signal.
+     *
+     * Categories become plain section headings rather than separately measured units, so there is a
+     * single bar for the whole surface; a per-milestone count appears only where one is genuinely in
+     * flight. Every milestone is listed, achieved ones included, with achievement carried by ONE
+     * encoding rather than four.
+     */
+    ProgressionTrackerVariant["FLAT"] = "flat";
+    /**
+     * Categories measured in their own right, with the full per-milestone breakdown.
+     *
+     * The densest shape, for a screen whose whole subject is progression. It keeps the per-category
+     * bar and the per-milestone count that `FLAT` collapses, and gives them different visual weight so
+     * they stop competing — the defect in the original was never that both existed, it was that they
+     * were rendered identically and so read as one confused signal.
+     */
+    ProgressionTrackerVariant["DETAILED"] = "detailed";
+})(ProgressionTrackerVariant || (ProgressionTrackerVariant = {}));
+/**
+ * The shape used when a mount does not name one.
+ *
+ * `SUMMARY` rather than `DETAILED`, deliberately: the overwhelmingly common mount is a card on a
+ * home surface, and the density that made the original hard to read is exactly what a card cannot
+ * afford. An application that wants everything asks for it.
+ */
+export const DEFAULT_PROGRESSION_TRACKER_VARIANT = ProgressionTrackerVariant.SUMMARY;
+/** @wildo_source:part:end saas.models.progression-tracker-variant */
+//# sourceMappingURL=progression-presentation.shared.schemas.js.map

package/dist/esm/guidance/progression-presentation.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progression-presentation.shared.schemas.js","sourceRoot":"","sources":["../../../../src/guidance/progression-presentation.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;oEAMoE;AAEpE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAN,IAAY,yBAuCX;AAvCD,WAAY,yBAAyB;IACnC;;;;;;;OAOG;IACH,0DAA6B,CAAA;IAE7B;;;;;;OAMG;IACH,gDAAmB,CAAA;IAEnB;;;;;;;OAOG;IACH,0CAAa,CAAA;IAEb;;;;;;;OAOG;IACH,kDAAqB,CAAA;AACvB,CAAC,EAvCW,yBAAyB,KAAzB,yBAAyB,QAuCpC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAA8B,yBAAyB,CAAC,OAAO,CAAC;AAChH,qEAAqE","sourcesContent":["/** ──────────────────────────────────────────────────────────────\n * Progression — Presentation Vocabulary\n *\n * How much of a person's progression a surface SHOWS. Distinct from\n * `progression-state.shared.schemas.ts`, which is what the product RECORDS, and from\n * `milestone-definition.shared.schemas.ts`, which is what an application DECLARES.\n * ────────────────────────────────────────────────────────────── */\n\n/**\n * @wildo_source:part:start saas.models.progression-tracker-variant facet:layer:shared facet:family:progression facet:audience:app-developer\n *\n * How much progression one `ProgressionMilestoneTracker` mount shows — passed as its `variant` prop.\n * Import from `@wildo-ai/saas-models`.\n *\n * Chosen PER MOUNT, because surfaces of one application want different amounts: a home dashboard\n * wants a glance, an achievements screen wants the detail, a product still teaching its first task\n * wants only the next thing to do. Every variant reads the same progression state and the same\n * milestone definitions; they differ only in how much of it reaches the screen.\n *\n * These four are the common shapes, not a ceiling — but the tracker is composed by name, not\n * resolved through the component registry, so there is no preset to swap. An application needing a\n * shape none of them covers builds its own card from `useProgression()` (exported by\n * `@wildo-ai/saas-frontend-lib`), which gives the same milestone definitions, per-scope state and\n * points total the tracker renders from.\n */\nexport enum ProgressionTrackerVariant {\n  /**\n   * Overall progress and the milestones actually in reach — nothing else.\n   *\n   * No categories, no points, no per-milestone bars, and ACHIEVED milestones are not listed at all:\n   * the \"5 of 8\" line is the record of them. For a surface whose job is to get someone to the next\n   * action rather than to celebrate the last one. The smallest shape, and the right default for a\n   * product that is still teaching itself.\n   */\n  NEXT_ACTIONS = 'next_actions',\n\n  /**\n   * A glance: overall progress, the points total, and the single next milestone.\n   *\n   * For a dashboard card sitting beside other cards, where progression is one of several things\n   * competing for the same screen. Pairs with a `DETAILED` mount on a dedicated view — this is the\n   * summary that links to it.\n   */\n  SUMMARY = 'summary',\n\n  /**\n   * One list and ONE progress signal.\n   *\n   * Categories become plain section headings rather than separately measured units, so there is a\n   * single bar for the whole surface; a per-milestone count appears only where one is genuinely in\n   * flight. Every milestone is listed, achieved ones included, with achievement carried by ONE\n   * encoding rather than four.\n   */\n  FLAT = 'flat',\n\n  /**\n   * Categories measured in their own right, with the full per-milestone breakdown.\n   *\n   * The densest shape, for a screen whose whole subject is progression. It keeps the per-category\n   * bar and the per-milestone count that `FLAT` collapses, and gives them different visual weight so\n   * they stop competing — the defect in the original was never that both existed, it was that they\n   * were rendered identically and so read as one confused signal.\n   */\n  DETAILED = 'detailed',\n}\n\n/**\n * The shape used when a mount does not name one.\n *\n * `SUMMARY` rather than `DETAILED`, deliberately: the overwhelmingly common mount is a card on a\n * home surface, and the density that made the original hard to read is exactly what a card cannot\n * afford. An application that wants everything asks for it.\n */\nexport const DEFAULT_PROGRESSION_TRACKER_VARIANT: ProgressionTrackerVariant = ProgressionTrackerVariant.SUMMARY;\n/** @wildo_source:part:end saas.models.progression-tracker-variant */\n"]}

package/dist/esm/guidance/progression-state.shared.resources-config.schemas.d.ts

@@ -18,6 +18,7 @@ export declare const userProgressionStateResourceConfiguration_InitializationFac
     totalPoints: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodNumber>>>;
     valueMomentsAchieved: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodObject<{
         signalsObserved: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodString>>;
+        signalOccurrenceCounts: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodNumber>>;
         achievedAt: import("zod").ZodOptional<import("zod").ZodCoercedDate<unknown>>;
     }, import("zod/v4/core").$strip>>>>;
     categoriesProgress: import("zod").ZodDefault<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodObject<{
@@ -36,6 +37,7 @@ export declare const organizationProgressionStateResourceConfiguration_Initializ
     totalPoints: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodNumber>>>;
     valueMomentsAchieved: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodObject<{
         signalsObserved: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodString>>;
+        signalOccurrenceCounts: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodNumber>>;
         achievedAt: import("zod").ZodOptional<import("zod").ZodCoercedDate<unknown>>;
     }, import("zod/v4/core").$strip>>>>;
     categoriesProgress: import("zod").ZodDefault<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodObject<{

package/dist/esm/guidance/progression-state.shared.resources-config.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"progression-state.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../src/guidance/progression-state.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAC;AACvF,OAAO,EAA8B,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAWzG,KAAK,kCAAkC,GACnC,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAE5B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,WAAW,CAAC;AAEtC,eAAO,MAAM,+DAA+D,GAAI,wBAAwB,oBAAoB,EAAE;;;;;;;;;;;;;;;;iCA2K5H,CAAC;AAIH,KAAK,0CAA0C,GAC3C,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,CAAC;AAEjC,eAAO,MAAM,uEAAuE,GAAI,wBAAwB,oBAAoB,EAAE;;;;;;;;;;;;;;;;iCAoGpI,CAAC"}
+{"version":3,"file":"progression-state.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../../src/guidance/progression-state.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAC;AACvF,OAAO,EAA8B,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAWzG,KAAK,kCAAkC,GACnC,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAE5B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,WAAW,CAAC;AAEtC,eAAO,MAAM,+DAA+D,GAAI,wBAAwB,oBAAoB,EAAE;;;;;;;;;;;;;;;;;iCA2K5H,CAAC;AAIH,KAAK,0CAA0C,GAC3C,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,CAAC;AAEjC,eAAO,MAAM,uEAAuE,GAAI,wBAAwB,oBAAoB,EAAE;;;;;;;;;;;;;;;;;iCAoGpI,CAAC"}

package/dist/esm/guidance/progression-state.shared.schemas.d.ts

@@ -39,6 +39,7 @@ export type ProgressionMilestoneAchieved = z.infer<typeof ProgressionMilestoneAc
  */
 export declare const ValueMomentStateSchema: z.ZodObject<{
     signalsObserved: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    signalOccurrenceCounts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
     achievedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
 }, z.core.$strip>;
 export type ValueMomentState = z.infer<typeof ValueMomentStateSchema>;
@@ -66,6 +67,7 @@ export declare const ProgressionStateSchema: z.ZodObject<{
     totalPoints: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodNumber>>>;
     valueMomentsAchieved: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         signalsObserved: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        signalOccurrenceCounts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
         achievedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     }, z.core.$strip>>>>;
     categoriesProgress: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -83,6 +85,7 @@ export declare const UserProgressionStateSchema: z.ZodObject<{
     totalPoints: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodNumber>>>;
     valueMomentsAchieved: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         signalsObserved: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        signalOccurrenceCounts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
         achievedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     }, z.core.$strip>>>>;
     categoriesProgress: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -101,6 +104,7 @@ export declare const OrganizationProgressionStateSchema: z.ZodObject<{
     totalPoints: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodNumber>>>;
     valueMomentsAchieved: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         signalsObserved: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        signalOccurrenceCounts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
         achievedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     }, z.core.$strip>>>>;
     categoriesProgress: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{

package/dist/esm/guidance/progression-state.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"progression-state.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/guidance/progression-state.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;oEAEoE;AAEpE,+CAA+C;AAC/C,eAAO,MAAM,kCAAkC;;;iBAK7C,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAE9F;;oEAEoE;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,sBAAsB;;;iBASjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;oEAEoE;AAEpE,uCAAuC;AACvC,eAAO,MAAM,iCAAiC;;;iBAK5C,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAE5F;;oEAEoE;AAEpE;;wDAEwD;AACxD,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;iBA8CjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;iBAErC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;iBAE7C,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAE9F,MAAM,MAAM,yBAAyB,GAAG,oBAAoB,GAAG,4BAA4B,CAAC"}
+{"version":3,"file":"progression-state.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/guidance/progression-state.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;oEAEoE;AAEpE,+CAA+C;AAC/C,eAAO,MAAM,kCAAkC;;;iBAK7C,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAE9F;;oEAEoE;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,sBAAsB;;;;iBAejC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;oEAEoE;AAEpE,uCAAuC;AACvC,eAAO,MAAM,iCAAiC;;;iBAK5C,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAE5F;;oEAEoE;AAEpE;;wDAEwD;AACxD,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;iBA8CjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;iBAErC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;iBAE7C,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAE9F,MAAM,MAAM,yBAAyB,GAAG,oBAAoB,GAAG,4BAA4B,CAAC"}

package/dist/esm/guidance/progression-state.shared.schemas.js

@@ -8,9 +8,9 @@ import { addImpersonalizeWith } from '@wildo-ai/zod-decorators';
 /** Record of a single milestone achievement */
 export const ProgressionMilestoneAchievedSchema = z.object({
     /** When the milestone was achieved */
-    achievedAt: z.coerce.date(),
+    achievedAt: z.coerce.date().describe('When the milestone was achieved.'),
     /** How many times the triggering operation occurred (for COUNT_THRESHOLD context) */
-    count: z.number().int().default(0),
+    count: z.number().int().default(0).describe('How many times the milestone\'s triggering operation had been performed when the milestone was achieved.'),
 });
 /** ──────────────────────────────────────────────────────────────
  * Progression State — Value Moment Record
@@ -47,9 +47,15 @@ export const ValueMomentStateSchema = z.object({
      * on the first signal and never needs this, but it is recorded for both so a moment whose mode is
      * changed after the fact does not silently lose the progress it already had.
      */
-    signalsObserved: z.array(z.string()).default([]),
+    signalsObserved: z.array(z.string()).default([]).describe('Signals observed so far. A signal that must occur several times is added once it reaches that count. The moment fires when any signal, or every signal, has been observed, depending on its mode.'),
+    /** Matching event occurrences per path-safe signal identity, accumulated per moment and scope.
+     * Optional for existing state rows; absent counts mean zero. Ordinary moment counters share the
+     * progression record's retention/erasure lifecycle. Anti-pattern counts remain instance-local.
+     */
+    signalOccurrenceCounts: z.record(z.string(), z.number().int().nonnegative()).optional()
+        .describe('Occurrences counted per signal, kept only for signals that must occur more than once before they count as observed. A missing count means zero.'),
     /** When the moment fired. Absent while it is still accumulating signals. */
-    achievedAt: z.coerce.date().optional(),
+    achievedAt: z.coerce.date().optional().describe('When the value moment fired. Absent while it is still collecting signals.'),
 });
 /** ──────────────────────────────────────────────────────────────
  * Progression State — Per-Category Aggregated Progress
@@ -57,9 +63,9 @@ export const ValueMomentStateSchema = z.object({
 /** Per-category aggregated progress */
 export const ProgressionCategoryProgressSchema = z.object({
     /** Number of milestones completed in this category */
-    completedCount: z.number().int().default(0),
+    completedCount: z.number().int().default(0).describe('Number of milestones achieved in this category.'),
     /** Total points earned in this category */
-    totalPoints: z.number().int().default(0),
+    totalPoints: z.number().int().default(0).describe('Points earned from the milestones achieved in this category.'),
 });
 /** ──────────────────────────────────────────────────────────────
  * Progression State — Top-Level Document

package/dist/esm/guidance/progression-state.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"progression-state.shared.schemas.js","sourceRoot":"","sources":["../../../src/guidance/progression-state.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\nimport { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas';\nimport { RedactionType } from '../compliance/privacy/redaction.shared.schemas';\nimport { addImpersonalizeWith } from '@wildo-ai/zod-decorators';\n\n/** ──────────────────────────────────────────────────────────────\n * Progression State — Milestone Achievement Record\n * ────────────────────────────────────────────────────────────── */\n\n/** Record of a single milestone achievement */\nexport const ProgressionMilestoneAchievedSchema = z.object({\n  /** When the milestone was achieved */\n  achievedAt: z.coerce.date(),\n  /** How many times the triggering operation occurred (for COUNT_THRESHOLD context) */\n  count: z.number().int().default(0),\n});\nexport type ProgressionMilestoneAchieved = z.infer<typeof ProgressionMilestoneAchievedSchema>;\n\n/** ──────────────────────────────────────────────────────────────\n * Progression State — Value Moment Record\n * ────────────────────────────────────────────────────────────── */\n\n/**\n * A value moment's state for one scope: what it has observed, and whether it fired.\n *\n * ## Why this lives on the progression state rather than in a resource of its own\n *\n * A value moment is an achievement keyed by an identifier, measured per USER or per ORGANIZATION,\n * derived from the same operation stream — the exact shape this row already holds for milestones,\n * with the same `PersonalDataCategory.USAGE` classification, the same erasure treatment, the same\n * subject-export provenance and the same `onParentCreate` / `onParentDelete` lifecycle. A second\n * resource would have re-declared every one of those obligations (#414).\n *\n * ## Why it is a SEPARATE FIELD from `milestonesAchieved`\n *\n * The two vocabularies are semantically distinct and their identifier spaces are independent: a\n * milestone is AUTHORED progression (dependencies, conditions, points, categories); a value moment\n * is a MEASURED behavioural moment (a `ValueMomentRole`, `ANY`/`ALL` composition over typed signals,\n * a cooldown, a suppressing `beforeStage`). Sharing one map would let a `milestoneRef` and a\n * `momentIdentifier` collide silently, and neither vocabulary constrains the other.\n *\n * ## What is NOT here, and why\n *\n * `ValueMomentRole.ANTI_PATTERN` is declared as NOT persisted — it re-fires on a cooldown rather than\n * being achieved once — so no anti-pattern ever writes a record here. Its cooldown is in-process; in\n * a multi-instance deployment each instance therefore keeps its own, which is what \"not persisted\"\n * means rather than a defect to fix here.\n */\nexport const ValueMomentStateSchema = z.object({\n  /**\n   * Signal keys observed so far, for `ValueMomentMode.ALL` composition. A moment in `ANY` mode fires\n   * on the first signal and never needs this, but it is recorded for both so a moment whose mode is\n   * changed after the fact does not silently lose the progress it already had.\n   */\n  signalsObserved: z.array(z.string()).default([]),\n  /** When the moment fired. Absent while it is still accumulating signals. */\n  achievedAt: z.coerce.date().optional(),\n});\nexport type ValueMomentState = z.infer<typeof ValueMomentStateSchema>;\n\n/** ──────────────────────────────────────────────────────────────\n * Progression State — Per-Category Aggregated Progress\n * ────────────────────────────────────────────────────────────── */\n\n/** Per-category aggregated progress */\nexport const ProgressionCategoryProgressSchema = z.object({\n  /** Number of milestones completed in this category */\n  completedCount: z.number().int().default(0),\n  /** Total points earned in this category */\n  totalPoints: z.number().int().default(0),\n});\nexport type ProgressionCategoryProgress = z.infer<typeof ProgressionCategoryProgressSchema>;\n\n/** ──────────────────────────────────────────────────────────────\n * Progression State — Top-Level Document\n * ────────────────────────────────────────────────────────────── */\n\n/** Shared progression state payload body.\n *  Scope-specific state resources extend this schema with their owning FK\n *  (`userId` / `organizationId`) before persistence. */\nexport const ProgressionStateSchema = z.object({\n  /** Map of milestoneRef → achievement record. Populated when a milestone is achieved. */\n  // USAGE — a per-person record of what they accomplished and how often they acted.\n  // RESET on erasure — returns this field to its schema default. It holds what this person achieved and when,\n  // which the category above correctly declares as personal data. RESET rather than REMOVE or MASK\n  // because the field is non-nullable WITH a `.default()`: REMOVE needs a clearable field and MASK\n  // needs a string. The value comes from the schema, so there is no second copy to drift.\n  milestonesAchieved: addImpersonalizeWith(\n  z.record(z.string(), ProgressionMilestoneAchievedSchema).default({})\n      .dataCategories(PersonalDataCategory.USAGE),\n    RedactionType.RESET,\n  ),\n  /** Map of `${resourceType}:${operation}` → count. Incremented on every matching operation.\n   *  This is the raw data used by COUNT_THRESHOLD conditions. */\n  // RESET on erasure — returns this field to its schema default. It holds how often they performed each operation,\n  // which the category above correctly declares as personal data. RESET rather than REMOVE or MASK\n  // because the field is non-nullable WITH a `.default()`: REMOVE needs a clearable field and MASK\n  // needs a string. The value comes from the schema, so there is no second copy to drift.\n  operationCounts: addImpersonalizeWith(\n  z.record(z.string(), z.number().int()).default({}).dataCategories(PersonalDataCategory.USAGE),\n    RedactionType.RESET,\n  ),\n  /** Total points across all achieved milestones. Updated atomically with achievements. */\n  // RESET on erasure — returns this field to its schema default. It holds their points total,\n  // which the category above correctly declares as personal data. RESET rather than REMOVE or MASK\n  // because the field is non-nullable WITH a `.default()`: REMOVE needs a clearable field and MASK\n  // needs a string. The value comes from the schema, so there is no second copy to drift.\n  totalPoints: addImpersonalizeWith(\n  z.number().int().default(0).isSummaryField().dataCategories(PersonalDataCategory.USAGE),\n    RedactionType.RESET,\n  ),\n  /** Map of momentIdentifier → value-moment state. See `ValueMomentStateSchema` for why it is\n   *  separate from `milestonesAchieved`. */\n  // USAGE — a per-person record of which product moments they reached and when.\n  // RESET on erasure — the same treatment as `milestonesAchieved` beside it, and for the same\n  // reasons: the USAGE category is accurate (these are observations the product made about a named\n  // person, so RETAIN_ONLY would be a false assertion), and the field is non-nullable WITH a\n  // `.default()`, so REMOVE needs a clearable field and MASK needs a string. RESET returns it to\n  // what it is when nobody has been observed, which is what erasure should leave behind.\n  valueMomentsAchieved: addImpersonalizeWith(\n    z.record(z.string(), ValueMomentStateSchema).default({})\n      .dataCategories(PersonalDataCategory.USAGE),\n    RedactionType.RESET,\n  ),\n  /** Per-category progress. Pre-aggregated for frontend display efficiency. */\n  categoriesProgress: z.record(z.string(), ProgressionCategoryProgressSchema).default({}),\n});\nexport type ProgressionState = z.infer<typeof ProgressionStateSchema>;\n\nexport const UserProgressionStateSchema = ProgressionStateSchema.extend({\n  userId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n});\nexport type UserProgressionState = z.infer<typeof UserProgressionStateSchema>;\n\nexport const OrganizationProgressionStateSchema = ProgressionStateSchema.extend({\n  organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n});\nexport type OrganizationProgressionState = z.infer<typeof OrganizationProgressionStateSchema>;\n\nexport type PersistedProgressionState = UserProgressionState | OrganizationProgressionState;\n"]}
+{"version":3,"file":"progression-state.shared.schemas.js","sourceRoot":"","sources":["../../../../src/guidance/progression-state.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\nimport { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas';\nimport { RedactionType } from '../compliance/privacy/redaction.shared.schemas';\nimport { addImpersonalizeWith } from '@wildo-ai/zod-decorators';\n\n/** ──────────────────────────────────────────────────────────────\n * Progression State — Milestone Achievement Record\n * ────────────────────────────────────────────────────────────── */\n\n/** Record of a single milestone achievement */\nexport const ProgressionMilestoneAchievedSchema = z.object({\n  /** When the milestone was achieved */\n  achievedAt: z.coerce.date().describe('When the milestone was achieved.'),\n  /** How many times the triggering operation occurred (for COUNT_THRESHOLD context) */\n  count: z.number().int().default(0).describe('How many times the milestone\\'s triggering operation had been performed when the milestone was achieved.'),\n});\nexport type ProgressionMilestoneAchieved = z.infer<typeof ProgressionMilestoneAchievedSchema>;\n\n/** ──────────────────────────────────────────────────────────────\n * Progression State — Value Moment Record\n * ────────────────────────────────────────────────────────────── */\n\n/**\n * A value moment's state for one scope: what it has observed, and whether it fired.\n *\n * ## Why this lives on the progression state rather than in a resource of its own\n *\n * A value moment is an achievement keyed by an identifier, measured per USER or per ORGANIZATION,\n * derived from the same operation stream — the exact shape this row already holds for milestones,\n * with the same `PersonalDataCategory.USAGE` classification, the same erasure treatment, the same\n * subject-export provenance and the same `onParentCreate` / `onParentDelete` lifecycle. A second\n * resource would have re-declared every one of those obligations (#414).\n *\n * ## Why it is a SEPARATE FIELD from `milestonesAchieved`\n *\n * The two vocabularies are semantically distinct and their identifier spaces are independent: a\n * milestone is AUTHORED progression (dependencies, conditions, points, categories); a value moment\n * is a MEASURED behavioural moment (a `ValueMomentRole`, `ANY`/`ALL` composition over typed signals,\n * a cooldown, a suppressing `beforeStage`). Sharing one map would let a `milestoneRef` and a\n * `momentIdentifier` collide silently, and neither vocabulary constrains the other.\n *\n * ## What is NOT here, and why\n *\n * `ValueMomentRole.ANTI_PATTERN` is declared as NOT persisted — it re-fires on a cooldown rather than\n * being achieved once — so no anti-pattern ever writes a record here. Its cooldown is in-process; in\n * a multi-instance deployment each instance therefore keeps its own, which is what \"not persisted\"\n * means rather than a defect to fix here.\n */\nexport const ValueMomentStateSchema = z.object({\n  /**\n   * Signal keys observed so far, for `ValueMomentMode.ALL` composition. A moment in `ANY` mode fires\n   * on the first signal and never needs this, but it is recorded for both so a moment whose mode is\n   * changed after the fact does not silently lose the progress it already had.\n   */\n  signalsObserved: z.array(z.string()).default([]).describe('Signals observed so far. A signal that must occur several times is added once it reaches that count. The moment fires when any signal, or every signal, has been observed, depending on its mode.'),\n  /** Matching event occurrences per path-safe signal identity, accumulated per moment and scope.\n   * Optional for existing state rows; absent counts mean zero. Ordinary moment counters share the\n   * progression record's retention/erasure lifecycle. Anti-pattern counts remain instance-local.\n   */\n  signalOccurrenceCounts: z.record(z.string(), z.number().int().nonnegative()).optional()\n    .describe('Occurrences counted per signal, kept only for signals that must occur more than once before they count as observed. A missing count means zero.'),\n  /** When the moment fired. Absent while it is still accumulating signals. */\n  achievedAt: z.coerce.date().optional().describe('When the value moment fired. Absent while it is still collecting signals.'),\n});\nexport type ValueMomentState = z.infer<typeof ValueMomentStateSchema>;\n\n/** ──────────────────────────────────────────────────────────────\n * Progression State — Per-Category Aggregated Progress\n * ────────────────────────────────────────────────────────────── */\n\n/** Per-category aggregated progress */\nexport const ProgressionCategoryProgressSchema = z.object({\n  /** Number of milestones completed in this category */\n  completedCount: z.number().int().default(0).describe('Number of milestones achieved in this category.'),\n  /** Total points earned in this category */\n  totalPoints: z.number().int().default(0).describe('Points earned from the milestones achieved in this category.'),\n});\nexport type ProgressionCategoryProgress = z.infer<typeof ProgressionCategoryProgressSchema>;\n\n/** ──────────────────────────────────────────────────────────────\n * Progression State — Top-Level Document\n * ────────────────────────────────────────────────────────────── */\n\n/** Shared progression state payload body.\n *  Scope-specific state resources extend this schema with their owning FK\n *  (`userId` / `organizationId`) before persistence. */\nexport const ProgressionStateSchema = z.object({\n  /** Map of milestoneRef → achievement record. Populated when a milestone is achieved. */\n  // USAGE — a per-person record of what they accomplished and how often they acted.\n  // RESET on erasure — returns this field to its schema default. It holds what this person achieved and when,\n  // which the category above correctly declares as personal data. RESET rather than REMOVE or MASK\n  // because the field is non-nullable WITH a `.default()`: REMOVE needs a clearable field and MASK\n  // needs a string. The value comes from the schema, so there is no second copy to drift.\n  milestonesAchieved: addImpersonalizeWith(\n  z.record(z.string(), ProgressionMilestoneAchievedSchema).default({})\n      .dataCategories(PersonalDataCategory.USAGE),\n    RedactionType.RESET,\n  ),\n  /** Map of `${resourceType}:${operation}` → count. Incremented on every matching operation.\n   *  This is the raw data used by COUNT_THRESHOLD conditions. */\n  // RESET on erasure — returns this field to its schema default. It holds how often they performed each operation,\n  // which the category above correctly declares as personal data. RESET rather than REMOVE or MASK\n  // because the field is non-nullable WITH a `.default()`: REMOVE needs a clearable field and MASK\n  // needs a string. The value comes from the schema, so there is no second copy to drift.\n  operationCounts: addImpersonalizeWith(\n  z.record(z.string(), z.number().int()).default({}).dataCategories(PersonalDataCategory.USAGE),\n    RedactionType.RESET,\n  ),\n  /** Total points across all achieved milestones. Updated atomically with achievements. */\n  // RESET on erasure — returns this field to its schema default. It holds their points total,\n  // which the category above correctly declares as personal data. RESET rather than REMOVE or MASK\n  // because the field is non-nullable WITH a `.default()`: REMOVE needs a clearable field and MASK\n  // needs a string. The value comes from the schema, so there is no second copy to drift.\n  totalPoints: addImpersonalizeWith(\n  z.number().int().default(0).isSummaryField().dataCategories(PersonalDataCategory.USAGE),\n    RedactionType.RESET,\n  ),\n  /** Map of momentIdentifier → value-moment state. See `ValueMomentStateSchema` for why it is\n   *  separate from `milestonesAchieved`. */\n  // USAGE — a per-person record of which product moments they reached and when.\n  // RESET on erasure — the same treatment as `milestonesAchieved` beside it, and for the same\n  // reasons: the USAGE category is accurate (these are observations the product made about a named\n  // person, so RETAIN_ONLY would be a false assertion), and the field is non-nullable WITH a\n  // `.default()`, so REMOVE needs a clearable field and MASK needs a string. RESET returns it to\n  // what it is when nobody has been observed, which is what erasure should leave behind.\n  valueMomentsAchieved: addImpersonalizeWith(\n    z.record(z.string(), ValueMomentStateSchema).default({})\n      .dataCategories(PersonalDataCategory.USAGE),\n    RedactionType.RESET,\n  ),\n  /** Per-category progress. Pre-aggregated for frontend display efficiency. */\n  categoriesProgress: z.record(z.string(), ProgressionCategoryProgressSchema).default({}),\n});\nexport type ProgressionState = z.infer<typeof ProgressionStateSchema>;\n\nexport const UserProgressionStateSchema = ProgressionStateSchema.extend({\n  userId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n});\nexport type UserProgressionState = z.infer<typeof UserProgressionStateSchema>;\n\nexport const OrganizationProgressionStateSchema = ProgressionStateSchema.extend({\n  organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n});\nexport type OrganizationProgressionState = z.infer<typeof OrganizationProgressionStateSchema>;\n\nexport type PersistedProgressionState = UserProgressionState | OrganizationProgressionState;\n"]}

package/dist/esm/http-api-binding/http-api-binding-id.shared.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-api-binding-id.shared.utils.d.ts","sourceRoot":"","sources":["../../../src/http-api-binding/http-api-binding-id.shared.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAmBH,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,mCAAmC,CAAC;AAE3C;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,6EAA6E;AAC7E,MAAM,MAAM,wBAAwB,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,4BAA4B,EAAE,MAA6B,CAAC;AA6DzE;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,OAAO,GAChB,wBAAwB,CA4C1B;AAaD;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE;IAAE,SAAS,EAAE,SAAS,eAAe,EAAE,CAAA;CAAE,EAClD,aAAa,EAAE,SAAS,OAAO,EAAE,GAChC,MAAM,CAqBR;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE;IAAE,SAAS,EAAE,SAAS,eAAe,EAAE,CAAA;CAAE,EAClD,UAAU,EAAE,MAAM,GACjB,wBAAwB,EAAE,CAqC5B;AAED,yCAAyC;AACzC,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEzE"}
+{"version":3,"file":"http-api-binding-id.shared.utils.d.ts","sourceRoot":"","sources":["../../../../src/http-api-binding/http-api-binding-id.shared.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAmBH,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,mCAAmC,CAAC;AAG3C;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,6EAA6E;AAC7E,MAAM,MAAM,wBAAwB,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,4BAA4B,EAAE,MAA6B,CAAC;AA6DzE;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,OAAO,GAChB,wBAAwB,CA4C1B;AAaD;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE;IAAE,SAAS,EAAE,SAAS,eAAe,EAAE,CAAA;CAAE,EAClD,aAAa,EAAE,SAAS,OAAO,EAAE,GAChC,MAAM,CAqBR;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE;IAAE,SAAS,EAAE,SAAS,eAAe,EAAE,CAAA;CAAE,EAClD,UAAU,EAAE,MAAM,GACjB,wBAAwB,EAAE,CAqC5B;AAED,yCAAyC;AACzC,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEzE"}

package/dist/esm/http-api-binding/http-api-binding-id.shared.utils.js

@@ -39,6 +39,7 @@
  * root-exported contract here ever starts inferring one.
  */
 import { HttpApiKeyComponentCodec, httpApiBindingUsesVerbatimKey, } from './http-api-binding.shared.schemas.js';
+import { describeCaughtError } from '../errors/caught-error-description.shared.utils.js';
 /**
  * The typed refusal every codec failure throws — undecodable ids, non-canonical aliases, missing
  * or malformed key components. Typed (rather than message-matched) so the backend adapter can
@@ -202,7 +203,7 @@ export function resolveHttpApiKeyComponents(binding, resourceId) {
             parsed = JSON.parse(new TextDecoder().decode(base64UrlToBytes(resourceId)));
         }
         catch (error) {
-            throw new HttpApiResourceIdError(`HTTP-API resource id '${resourceId}' is not a valid encoded composite key: ${error instanceof Error ? error.message : String(error)}`);
+            throw new HttpApiResourceIdError(`HTTP-API resource id '${resourceId}' is not a valid encoded composite key: ${describeCaughtError(error)}`);
         }
         if (!Array.isArray(parsed) || parsed.length !== binding.keyFields.length) {
             throw new HttpApiResourceIdError(`HTTP-API resource id '${resourceId}' decodes to ${Array.isArray(parsed) ? `${parsed.length} component(s)` : 'a non-array'} for a binding declaring ${binding.keyFields.length}.`);

package/dist/esm/http-api-binding/http-api-binding-id.shared.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"http-api-binding-id.shared.utils.js","sourceRoot":"","sources":["../../../../src/http-api-binding/http-api-binding-id.shared.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EACL,wBAAwB,EACxB,6BAA6B,GAE9B,MAAM,mCAAmC,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAKD;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAW,oBAAoB,CAAC;AAEzE,MAAM,YAAY,GAAG,+EAA+E,CAAC;AAErG,mCAAmC;AACnC,iCAAiC;AACjC,mCAAmC;AAEnC,MAAM,eAAe,GAAG,kEAAkE,CAAC;AAE3F,MAAM,cAAc,GAAgC,IAAI,GAAG,CACzD,CAAC,GAAG,eAAe,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CACzD,CAAC;AAEF,SAAS,gBAAgB,CAAC,KAAiB;IACzC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACpB,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3D,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3D,GAAG,IAAI,eAAe,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;QAChC,GAAG,IAAI,eAAe,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC9D,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;YACrB,GAAG,IAAI,eAAe,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAChE,CAAC;QACD,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;YACrB,GAAG,IAAI,eAAe,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,gBAAgB,CAAC,OAAe;IACvC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,sBAAsB,CAAC,oEAAoE,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;IAC3H,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC;IACzC,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,sBAAsB,CAAC,gCAAgC,IAAI,4BAA4B,CAAC,CAAC;QACrG,CAAC;QACD,MAAM,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC;QAC/B,YAAY,IAAI,CAAC,CAAC;QAClB,IAAI,YAAY,IAAI,CAAC,EAAE,CAAC;YACtB,YAAY,IAAI,CAAC,CAAC;YAClB,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,IAAI,YAAY,CAAC,GAAG,IAAI,CAAC;YACnD,SAAS,IAAI,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,mCAAmC;AACnC,oCAAoC;AACpC,mCAAmC;AAEnC;;;;GAIG;AACH,MAAM,UAAU,4BAA4B,CAC1C,QAAyB,EACzB,QAAiB;IAEjB,QAAQ,QAAQ,CAAC,KAAK,EAAE,CAAC;QACvB,KAAK,wBAAwB,CAAC,MAAM,CAAC,CAAC,CAAC;YACrC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC1D,MAAM,IAAI,sBAAsB,CAC9B,2BAA2B,QAAQ,CAAC,WAAW,oDAAoD,aAAa,CAAC,QAAQ,CAAC,GAAG,CAC9H,CAAC;YACJ,CAAC;YACD,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,KAAK,wBAAwB,CAAC,OAAO,CAAC,CAAC,CAAC;YACtC,MAAM,OAAO,GAAG,OAAO,QAAQ,KAAK,QAAQ,IAAI,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;YACvG,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;gBAClE,MAAM,IAAI,sBAAsB,CAC9B,2BAA2B,QAAQ,CAAC,WAAW,iDAAiD,aAAa,CAAC,QAAQ,CAAC,GAAG,CAC3H,CAAC;YACJ,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,KAAK,wBAAwB,CAAC,IAAI,CAAC,CAAC,CAAC;YACnC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACjE,MAAM,IAAI,sBAAsB,CAC9B,2BAA2B,QAAQ,CAAC,WAAW,6CAA6C,aAAa,CAAC,QAAQ,CAAC,GAAG,CACvH,CAAC;YACJ,CAAC;YACD,8FAA8F;YAC9F,OAAO,QAAQ,CAAC,WAAW,EAAE,CAAC;QAChC,CAAC;QACD,KAAK,wBAAwB,CAAC,YAAY,CAAC,CAAC,CAAC;YAC3C,wEAAwE;YACxE,qFAAqF;YACrF,uFAAuF;YACvF,iCAAiC;YACjC,MAAM,WAAW,GAAG,OAAO,QAAQ,KAAK,QAAQ;mBAC3C,0EAA0E,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC/F,MAAM,SAAS,GAAG,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAkB,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;YAC5E,IAAI,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC5B,MAAM,IAAI,sBAAsB,CAC9B,2BAA2B,QAAQ,CAAC,WAAW,2FAA2F,aAAa,CAAC,QAAQ,CAAC,GAAG,CACrK,CAAC;YACJ,CAAC;YACD,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;QAC3C,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,IAAI,KAAK,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC;IACrE,CAAC;IACD,OAAO,GAAG,OAAO,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAC5C,CAAC;AAED,mCAAmC;AACnC,qCAAqC;AACrC,mCAAmC;AAEnC;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CACzC,OAAkD,EAClD,aAAiC;IAEjC,IAAI,aAAa,CAAC,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;QACtD,MAAM,IAAI,sBAAsB,CAC9B,kCAAkC,aAAa,CAAC,MAAM,6CAA6C,OAAO,CAAC,SAAS,CAAC,MAAM,GAAG,CAC/H,CAAC;IACJ,CAAC;IACD,MAAM,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE,CAC3D,4BAA4B,CAAC,QAAQ,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC,CAC7D,CAAC;IAEF,IAAI,6BAA6B,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3C,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QACvC,+FAA+F;QAC/F,iFAAiF;QACjF,iBAAiB,CAAC,QAAQ,CAAC,CAAC;QAC5B,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IACvF,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC3B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,2BAA2B,CACzC,OAAkD,EAClD,UAAkB;IAElB,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,sBAAsB,CAAC,kDAAkD,CAAC,CAAC;IACvF,CAAC;IAED,IAAI,UAAsC,CAAC;IAC3C,IAAI,6BAA6B,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3C,UAAU,GAAG,CAAC,4BAA4B,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;IAChF,CAAC;SAAM,CAAC;QACN,iBAAiB,CAAC,UAAU,CAAC,CAAC;QAC9B,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC9E,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,sBAAsB,CAC9B,yBAAyB,UAAU,2CAA2C,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACvI,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;YACzE,MAAM,IAAI,sBAAsB,CAC9B,yBAAyB,UAAU,gBAAgB,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,eAAe,CAAC,CAAC,CAAC,aAAa,4BAA4B,OAAO,CAAC,SAAS,CAAC,MAAM,GAAG,CAClL,CAAC;QACJ,CAAC;QACD,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC,4BAA4B,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACjH,CAAC;IAED,8FAA8F;IAC9F,0FAA0F;IAC1F,6FAA6F;IAC7F,sFAAsF;IACtF,MAAM,SAAS,GAAG,2BAA2B,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACnE,IAAI,SAAS,KAAK,UAAU,EAAE,CAAC;QAC7B,MAAM,IAAI,sBAAsB,CAC9B,wBAAwB,aAAa,CAAC,UAAU,CAAC,gCAAgC,aAAa,CAAC,SAAS,CAAC,8DAA8D,CACxK,CAAC;IACJ,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,8BAA8B,CAAC,SAAiB;IAC9D,OAAO,4BAA4B,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,iBAAiB,CAAC,SAAiB;IAC1C,IAAI,CAAC,8BAA8B,CAAC,SAAS,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,sBAAsB,CAC9B,iDAAiD,4BAA4B,KAAK,aAAa,CAAC,SAAS,CAAC,IAAI;cAC5G,mIAAmI,CACtI,CAAC;IACJ,CAAC;AACH,CAAC","sourcesContent":["/**\n * HTTP-API resource-id synthesis — THE single authority for encoding/decoding the engine-facing\n * `_id` of an `HTTP_API`-backed resource from its remote key components.\n *\n * Contract (design paper `.claude/plans/etl-composite-key-synthesis.md`):\n * - **Deterministic + injective**: the same remote row yields the same `_id` on every machine,\n *   forever; two rows never collide (JSON array encoding preserves order and type).\n * - **Charset law**: every synthesized id matches `^[A-Za-z0-9._~-]+$` (URL-unreserved). This is\n *   what survives the two measured hazards: the frontend's unencoded `String.replace` URL\n *   substitution (forbids `/ ? # % $`) and colon-parsed websocket-room / Redis keys (forbids `:`).\n * - **Two static forms**, selected by the BINDING, never sniffed per row:\n *   verbatim (single key whose codec's whole value space is charset-safe — GUID, INTEGER) or\n *   encoded (base64url of the canonical JSON array of normalized components, no padding).\n * - **Decodable offline**: `_id` → key components needs no remote call.\n *\n * Errors are thrown as the typed {@link HttpApiResourceIdError} — this module is shared-tier (no\n * `ErrorBuilder` here; same precedent as `selectByPersistenceAdapter`). Backend callers classify\n * it by INSTANCE into a LOUD `VALIDATION` refusal — never a silent not-found (the Mongo\n * CastError-to-404 behavior is explicitly NOT mimicked).\n *\n * No `Buffer` here on purpose: this file must run in the browser bundle as well as Node, so\n * base64url is implemented over `TextEncoder`/`TextDecoder`.\n */\n\n/*\n * entrypoint-closure-waiver: this root-reachable module imports the external-data AUTHORING\n * contract, which only `@wildo-ai/saas-models/external-data` publishes (see\n * `external-data.exports.ts` for why that subpath exists).\n *\n * MEASURED SAFE 2026-08-29 by the probe `package-public-entrypoints.md` prescribes — a consumer\n * importing ONLY the package root, re-exporting these surfaces and deriving their parameter types\n * so declaration emit must WRITE them rather than alias them, compiled with `declaration: true`:\n * zero TS2742 / TS2883 / TS7056, and the emitted `.d.ts` names `@wildo-ai/saas-models` with no\n * `node_modules/...` path anywhere in it.\n *\n * The mechanism, so the next reader need not re-derive it: every crossing here is an EXPLICIT\n * ANNOTATION inside this package, so TypeScript emits a RELATIVE intra-package import in our own\n * `.d.ts` — which resolves by PATH for any consumer, whatever the exports map says. TS2742 bites\n * only when TypeScript must INVENT a specifier for an INFERRED type. Re-run the probe if a\n * root-exported contract here ever starts inferring one.\n */\nimport {\n  HttpApiKeyComponentCodec,\n  httpApiBindingUsesVerbatimKey,\n  type HttpApiKeyField,\n} from './http-api-binding.shared.schemas';\n\n/**\n * The typed refusal every codec failure throws — undecodable ids, non-canonical aliases, missing\n * or malformed key components. Typed (rather than message-matched) so the backend adapter can\n * classify it into a VALIDATION projection without regexing prose that a reword would silently\n * break.\n */\nexport class HttpApiResourceIdError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'HttpApiResourceIdError';\n  }\n}\n\n/** One normalized key component value as it participates in id synthesis. */\nexport type HttpApiKeyComponentValue = string | number;\n\n/**\n * The charset law for every synthesized HTTP-API resource id: URL-unreserved characters only.\n * See the module JSDoc for the two measured hazards this survives.\n */\nexport const HTTP_API_RESOURCE_ID_CHARSET: RegExp = /^[A-Za-z0-9._~-]+$/;\n\nconst GUID_PATTERN = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;\n\n// --------------------------------\n// base64url (portable, unpadded)\n// --------------------------------\n\nconst B64URL_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';\n\nconst B64URL_REVERSE: ReadonlyMap<string, number> = new Map(\n  [...B64URL_ALPHABET].map((char, index) => [char, index]),\n);\n\nfunction bytesToBase64Url(bytes: Uint8Array): string {\n  let out = '';\n  for (let i = 0; i < bytes.length; i += 3) {\n    const b0 = bytes[i];\n    const b1 = i + 1 < bytes.length ? bytes[i + 1] : undefined;\n    const b2 = i + 2 < bytes.length ? bytes[i + 2] : undefined;\n    out += B64URL_ALPHABET[b0 >> 2];\n    out += B64URL_ALPHABET[((b0 & 0x03) << 4) | ((b1 ?? 0) >> 4)];\n    if (b1 !== undefined) {\n      out += B64URL_ALPHABET[((b1 & 0x0f) << 2) | ((b2 ?? 0) >> 6)];\n    }\n    if (b2 !== undefined) {\n      out += B64URL_ALPHABET[b2 & 0x3f];\n    }\n  }\n  return out;\n}\n\nfunction base64UrlToBytes(encoded: string): Uint8Array {\n  if (encoded.length % 4 === 1) {\n    throw new HttpApiResourceIdError(`Invalid base64url payload length in HTTP-API resource id (length ${encoded.length}).`);\n  }\n  const byteLength = Math.floor((encoded.length * 3) / 4);\n  const bytes = new Uint8Array(byteLength);\n  let byteIndex = 0;\n  let buffer = 0;\n  let bitsInBuffer = 0;\n  for (const char of encoded) {\n    const value = B64URL_REVERSE.get(char);\n    if (value === undefined) {\n      throw new HttpApiResourceIdError(`Invalid base64url character '${char}' in HTTP-API resource id.`);\n    }\n    buffer = (buffer << 6) | value;\n    bitsInBuffer += 6;\n    if (bitsInBuffer >= 8) {\n      bitsInBuffer -= 8;\n      bytes[byteIndex] = (buffer >> bitsInBuffer) & 0xff;\n      byteIndex += 1;\n    }\n  }\n  return bytes;\n}\n\n// --------------------------------\n// Component normalization per codec\n// --------------------------------\n\n/**\n * Normalize one raw remote key value per its declared codec. Normalization is what makes the\n * synthesis STABLE: the same remote row must produce byte-identical components regardless of the\n * remote system's incidental formatting (GUID casing, datetime precision).\n */\nexport function normalizeHttpApiKeyComponent(\n  keyField: HttpApiKeyField,\n  rawValue: unknown,\n): HttpApiKeyComponentValue {\n  switch (keyField.codec) {\n    case HttpApiKeyComponentCodec.STRING: {\n      if (typeof rawValue !== 'string' || rawValue.length === 0) {\n        throw new HttpApiResourceIdError(\n          `HTTP-API key component '${keyField.remoteField}' (codec STRING) must be a non-empty string, got ${describeValue(rawValue)}.`,\n        );\n      }\n      return rawValue;\n    }\n    case HttpApiKeyComponentCodec.INTEGER: {\n      const numeric = typeof rawValue === 'string' && /^-?\\d+$/.test(rawValue) ? Number(rawValue) : rawValue;\n      if (typeof numeric !== 'number' || !Number.isSafeInteger(numeric)) {\n        throw new HttpApiResourceIdError(\n          `HTTP-API key component '${keyField.remoteField}' (codec INTEGER) must be a safe integer, got ${describeValue(rawValue)}.`,\n        );\n      }\n      return numeric;\n    }\n    case HttpApiKeyComponentCodec.GUID: {\n      if (typeof rawValue !== 'string' || !GUID_PATTERN.test(rawValue)) {\n        throw new HttpApiResourceIdError(\n          `HTTP-API key component '${keyField.remoteField}' (codec GUID) must be a GUID string, got ${describeValue(rawValue)}.`,\n        );\n      }\n      // Lowercase so the same remote row synthesizes the same id regardless of the target's casing.\n      return rawValue.toLowerCase();\n    }\n    case HttpApiKeyComponentCodec.DATETIME_ISO: {\n      // Strict ISO 8601 shape gate BEFORE Date.parse: bare Date.parse accepts\n      // implementation-defined non-ISO formats, which would make the synthesized id differ\n      // across JS engines — the determinism the module contract promises would silently hold\n      // only for genuinely ISO inputs.\n      const isStrictIso = typeof rawValue === 'string'\n        && /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,9})?(?:Z|[+-]\\d{2}:\\d{2})$/.test(rawValue);\n      const timestamp = isStrictIso ? Date.parse(rawValue as string) : Number.NaN;\n      if (Number.isNaN(timestamp)) {\n        throw new HttpApiResourceIdError(\n          `HTTP-API key component '${keyField.remoteField}' (codec DATETIME_ISO) must be an ISO 8601 datetime string with an explicit offset, got ${describeValue(rawValue)}.`,\n        );\n      }\n      return new Date(timestamp).toISOString();\n    }\n  }\n}\n\nfunction describeValue(value: unknown): string {\n  if (typeof value === 'string') {\n    return `'${value.length > 64 ? `${value.slice(0, 64)}…` : value}'`;\n  }\n  return `${typeof value} ${String(value)}`;\n}\n\n// --------------------------------\n// Encode / decode (the two id forms)\n// --------------------------------\n\n/**\n * Synthesize the engine-facing `_id` for one remote row, from its raw remote key values in\n * `keyFields` order. The form (verbatim vs encoded) is a static property of the binding\n * (`httpApiBindingUsesVerbatimKey`).\n */\nexport function synthesizeHttpApiResourceId(\n  binding: { keyFields: readonly HttpApiKeyField[] },\n  rawComponents: readonly unknown[],\n): string {\n  if (rawComponents.length !== binding.keyFields.length) {\n    throw new HttpApiResourceIdError(\n      `HTTP-API id synthesis received ${rawComponents.length} key component(s) for a binding declaring ${binding.keyFields.length}.`,\n    );\n  }\n  const normalized = binding.keyFields.map((keyField, index) =>\n    normalizeHttpApiKeyComponent(keyField, rawComponents[index]),\n  );\n\n  if (httpApiBindingUsesVerbatimKey(binding)) {\n    const verbatim = String(normalized[0]);\n    // Defensive: the codec gate should make this unreachable, but the charset law is the invariant\n    // every downstream consumer relies on, so it is asserted where the id is minted.\n    assertCharsetSafe(verbatim);\n    return verbatim;\n  }\n\n  const encoded = bytesToBase64Url(new TextEncoder().encode(JSON.stringify(normalized)));\n  assertCharsetSafe(encoded);\n  return encoded;\n}\n\n/**\n * Resolve an engine-facing `_id` back to its normalized key components, in `keyFields` order.\n * Purely local — no remote call. Throws on any id this binding could not have synthesized —\n * INCLUDING every non-canonical ALIAS of a valid id (base64url trailing-bit variants,\n * JSON-whitespace variants, non-normalized verbatim forms such as an uppercase GUID): one remote\n * row answers to exactly ONE engine id, because row identity, URL canonicality, dedup keys and\n * id-based exclusion filters are all built on that equality. Enforced by re-synthesizing from the\n * resolved components and requiring byte-equality with the incoming id.\n */\nexport function resolveHttpApiKeyComponents(\n  binding: { keyFields: readonly HttpApiKeyField[] },\n  resourceId: string,\n): HttpApiKeyComponentValue[] {\n  if (resourceId.length === 0) {\n    throw new HttpApiResourceIdError('HTTP-API resource id must be a non-empty string.');\n  }\n\n  let components: HttpApiKeyComponentValue[];\n  if (httpApiBindingUsesVerbatimKey(binding)) {\n    components = [normalizeHttpApiKeyComponent(binding.keyFields[0], resourceId)];\n  } else {\n    assertCharsetSafe(resourceId);\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(new TextDecoder().decode(base64UrlToBytes(resourceId)));\n    } catch (error) {\n      throw new HttpApiResourceIdError(\n        `HTTP-API resource id '${resourceId}' is not a valid encoded composite key: ${error instanceof Error ? error.message : String(error)}`,\n      );\n    }\n    if (!Array.isArray(parsed) || parsed.length !== binding.keyFields.length) {\n      throw new HttpApiResourceIdError(\n        `HTTP-API resource id '${resourceId}' decodes to ${Array.isArray(parsed) ? `${parsed.length} component(s)` : 'a non-array'} for a binding declaring ${binding.keyFields.length}.`,\n      );\n    }\n    components = binding.keyFields.map((keyField, index) => normalizeHttpApiKeyComponent(keyField, parsed[index]));\n  }\n\n  // Canonicality gate: re-synthesize and require byte-equality. Normalization is idempotent per\n  // codec, so a canonical id always round-trips to itself; any alias (dropped-bit base64url\n  // variant, whitespace-bearing JSON, '042' for an INTEGER key, 'ABC…' for a GUID key) differs\n  // here and is refused rather than silently adopted as a second name for the same row.\n  const canonical = synthesizeHttpApiResourceId(binding, components);\n  if (canonical !== resourceId) {\n    throw new HttpApiResourceIdError(\n      `HTTP-API resource id ${describeValue(resourceId)} is a non-canonical alias of ${describeValue(canonical)} and is refused: every remote row has exactly one engine id.`,\n    );\n  }\n  return components;\n}\n\n/** Runtime guard for the charset law. */\nexport function isCharsetSafeHttpApiResourceId(candidate: string): boolean {\n  return HTTP_API_RESOURCE_ID_CHARSET.test(candidate);\n}\n\nfunction assertCharsetSafe(candidate: string): void {\n  if (!isCharsetSafeHttpApiResourceId(candidate)) {\n    throw new HttpApiResourceIdError(\n      `HTTP-API resource id violates the charset law ${HTTP_API_RESOURCE_ID_CHARSET}: ${describeValue(candidate)}. `\n      + 'Ids must stay URL-unreserved — the frontend substitutes them into URLs without encoding, and websocket room names parse on \\':\\'.',\n    );\n  }\n}\n"]}
+{"version":3,"file":"http-api-binding-id.shared.utils.js","sourceRoot":"","sources":["../../../../src/http-api-binding/http-api-binding-id.shared.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * HTTP-API resource-id synthesis — THE single authority for encoding/decoding the engine-facing\n * `_id` of an `HTTP_API`-backed resource from its remote key components.\n *\n * Contract (design paper `.claude/plans/etl-composite-key-synthesis.md`):\n * - **Deterministic + injective**: the same remote row yields the same `_id` on every machine,\n *   forever; two rows never collide (JSON array encoding preserves order and type).\n * - **Charset law**: every synthesized id matches `^[A-Za-z0-9._~-]+$` (URL-unreserved). This is\n *   what survives the two measured hazards: the frontend's unencoded `String.replace` URL\n *   substitution (forbids `/ ? # % $`) and colon-parsed websocket-room / Redis keys (forbids `:`).\n * - **Two static forms**, selected by the BINDING, never sniffed per row:\n *   verbatim (single key whose codec's whole value space is charset-safe — GUID, INTEGER) or\n *   encoded (base64url of the canonical JSON array of normalized components, no padding).\n * - **Decodable offline**: `_id` → key components needs no remote call.\n *\n * Errors are thrown as the typed {@link HttpApiResourceIdError} — this module is shared-tier (no\n * `ErrorBuilder` here; same precedent as `selectByPersistenceAdapter`). Backend callers classify\n * it by INSTANCE into a LOUD `VALIDATION` refusal — never a silent not-found (the Mongo\n * CastError-to-404 behavior is explicitly NOT mimicked).\n *\n * No `Buffer` here on purpose: this file must run in the browser bundle as well as Node, so\n * base64url is implemented over `TextEncoder`/`TextDecoder`.\n */\n\n/*\n * entrypoint-closure-waiver: this root-reachable module imports the external-data AUTHORING\n * contract, which only `@wildo-ai/saas-models/external-data` publishes (see\n * `external-data.exports.ts` for why that subpath exists).\n *\n * MEASURED SAFE 2026-08-29 by the probe `package-public-entrypoints.md` prescribes — a consumer\n * importing ONLY the package root, re-exporting these surfaces and deriving their parameter types\n * so declaration emit must WRITE them rather than alias them, compiled with `declaration: true`:\n * zero TS2742 / TS2883 / TS7056, and the emitted `.d.ts` names `@wildo-ai/saas-models` with no\n * `node_modules/...` path anywhere in it.\n *\n * The mechanism, so the next reader need not re-derive it: every crossing here is an EXPLICIT\n * ANNOTATION inside this package, so TypeScript emits a RELATIVE intra-package import in our own\n * `.d.ts` — which resolves by PATH for any consumer, whatever the exports map says. TS2742 bites\n * only when TypeScript must INVENT a specifier for an INFERRED type. Re-run the probe if a\n * root-exported contract here ever starts inferring one.\n */\nimport {\n  HttpApiKeyComponentCodec,\n  httpApiBindingUsesVerbatimKey,\n  type HttpApiKeyField,\n} from './http-api-binding.shared.schemas';\n\nimport { describeCaughtError } from '../errors/caught-error-description.shared.utils';\n/**\n * The typed refusal every codec failure throws — undecodable ids, non-canonical aliases, missing\n * or malformed key components. Typed (rather than message-matched) so the backend adapter can\n * classify it into a VALIDATION projection without regexing prose that a reword would silently\n * break.\n */\nexport class HttpApiResourceIdError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'HttpApiResourceIdError';\n  }\n}\n\n/** One normalized key component value as it participates in id synthesis. */\nexport type HttpApiKeyComponentValue = string | number;\n\n/**\n * The charset law for every synthesized HTTP-API resource id: URL-unreserved characters only.\n * See the module JSDoc for the two measured hazards this survives.\n */\nexport const HTTP_API_RESOURCE_ID_CHARSET: RegExp = /^[A-Za-z0-9._~-]+$/;\n\nconst GUID_PATTERN = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;\n\n// --------------------------------\n// base64url (portable, unpadded)\n// --------------------------------\n\nconst B64URL_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';\n\nconst B64URL_REVERSE: ReadonlyMap<string, number> = new Map(\n  [...B64URL_ALPHABET].map((char, index) => [char, index]),\n);\n\nfunction bytesToBase64Url(bytes: Uint8Array): string {\n  let out = '';\n  for (let i = 0; i < bytes.length; i += 3) {\n    const b0 = bytes[i];\n    const b1 = i + 1 < bytes.length ? bytes[i + 1] : undefined;\n    const b2 = i + 2 < bytes.length ? bytes[i + 2] : undefined;\n    out += B64URL_ALPHABET[b0 >> 2];\n    out += B64URL_ALPHABET[((b0 & 0x03) << 4) | ((b1 ?? 0) >> 4)];\n    if (b1 !== undefined) {\n      out += B64URL_ALPHABET[((b1 & 0x0f) << 2) | ((b2 ?? 0) >> 6)];\n    }\n    if (b2 !== undefined) {\n      out += B64URL_ALPHABET[b2 & 0x3f];\n    }\n  }\n  return out;\n}\n\nfunction base64UrlToBytes(encoded: string): Uint8Array {\n  if (encoded.length % 4 === 1) {\n    throw new HttpApiResourceIdError(`Invalid base64url payload length in HTTP-API resource id (length ${encoded.length}).`);\n  }\n  const byteLength = Math.floor((encoded.length * 3) / 4);\n  const bytes = new Uint8Array(byteLength);\n  let byteIndex = 0;\n  let buffer = 0;\n  let bitsInBuffer = 0;\n  for (const char of encoded) {\n    const value = B64URL_REVERSE.get(char);\n    if (value === undefined) {\n      throw new HttpApiResourceIdError(`Invalid base64url character '${char}' in HTTP-API resource id.`);\n    }\n    buffer = (buffer << 6) | value;\n    bitsInBuffer += 6;\n    if (bitsInBuffer >= 8) {\n      bitsInBuffer -= 8;\n      bytes[byteIndex] = (buffer >> bitsInBuffer) & 0xff;\n      byteIndex += 1;\n    }\n  }\n  return bytes;\n}\n\n// --------------------------------\n// Component normalization per codec\n// --------------------------------\n\n/**\n * Normalize one raw remote key value per its declared codec. Normalization is what makes the\n * synthesis STABLE: the same remote row must produce byte-identical components regardless of the\n * remote system's incidental formatting (GUID casing, datetime precision).\n */\nexport function normalizeHttpApiKeyComponent(\n  keyField: HttpApiKeyField,\n  rawValue: unknown,\n): HttpApiKeyComponentValue {\n  switch (keyField.codec) {\n    case HttpApiKeyComponentCodec.STRING: {\n      if (typeof rawValue !== 'string' || rawValue.length === 0) {\n        throw new HttpApiResourceIdError(\n          `HTTP-API key component '${keyField.remoteField}' (codec STRING) must be a non-empty string, got ${describeValue(rawValue)}.`,\n        );\n      }\n      return rawValue;\n    }\n    case HttpApiKeyComponentCodec.INTEGER: {\n      const numeric = typeof rawValue === 'string' && /^-?\\d+$/.test(rawValue) ? Number(rawValue) : rawValue;\n      if (typeof numeric !== 'number' || !Number.isSafeInteger(numeric)) {\n        throw new HttpApiResourceIdError(\n          `HTTP-API key component '${keyField.remoteField}' (codec INTEGER) must be a safe integer, got ${describeValue(rawValue)}.`,\n        );\n      }\n      return numeric;\n    }\n    case HttpApiKeyComponentCodec.GUID: {\n      if (typeof rawValue !== 'string' || !GUID_PATTERN.test(rawValue)) {\n        throw new HttpApiResourceIdError(\n          `HTTP-API key component '${keyField.remoteField}' (codec GUID) must be a GUID string, got ${describeValue(rawValue)}.`,\n        );\n      }\n      // Lowercase so the same remote row synthesizes the same id regardless of the target's casing.\n      return rawValue.toLowerCase();\n    }\n    case HttpApiKeyComponentCodec.DATETIME_ISO: {\n      // Strict ISO 8601 shape gate BEFORE Date.parse: bare Date.parse accepts\n      // implementation-defined non-ISO formats, which would make the synthesized id differ\n      // across JS engines — the determinism the module contract promises would silently hold\n      // only for genuinely ISO inputs.\n      const isStrictIso = typeof rawValue === 'string'\n        && /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,9})?(?:Z|[+-]\\d{2}:\\d{2})$/.test(rawValue);\n      const timestamp = isStrictIso ? Date.parse(rawValue as string) : Number.NaN;\n      if (Number.isNaN(timestamp)) {\n        throw new HttpApiResourceIdError(\n          `HTTP-API key component '${keyField.remoteField}' (codec DATETIME_ISO) must be an ISO 8601 datetime string with an explicit offset, got ${describeValue(rawValue)}.`,\n        );\n      }\n      return new Date(timestamp).toISOString();\n    }\n  }\n}\n\nfunction describeValue(value: unknown): string {\n  if (typeof value === 'string') {\n    return `'${value.length > 64 ? `${value.slice(0, 64)}…` : value}'`;\n  }\n  return `${typeof value} ${String(value)}`;\n}\n\n// --------------------------------\n// Encode / decode (the two id forms)\n// --------------------------------\n\n/**\n * Synthesize the engine-facing `_id` for one remote row, from its raw remote key values in\n * `keyFields` order. The form (verbatim vs encoded) is a static property of the binding\n * (`httpApiBindingUsesVerbatimKey`).\n */\nexport function synthesizeHttpApiResourceId(\n  binding: { keyFields: readonly HttpApiKeyField[] },\n  rawComponents: readonly unknown[],\n): string {\n  if (rawComponents.length !== binding.keyFields.length) {\n    throw new HttpApiResourceIdError(\n      `HTTP-API id synthesis received ${rawComponents.length} key component(s) for a binding declaring ${binding.keyFields.length}.`,\n    );\n  }\n  const normalized = binding.keyFields.map((keyField, index) =>\n    normalizeHttpApiKeyComponent(keyField, rawComponents[index]),\n  );\n\n  if (httpApiBindingUsesVerbatimKey(binding)) {\n    const verbatim = String(normalized[0]);\n    // Defensive: the codec gate should make this unreachable, but the charset law is the invariant\n    // every downstream consumer relies on, so it is asserted where the id is minted.\n    assertCharsetSafe(verbatim);\n    return verbatim;\n  }\n\n  const encoded = bytesToBase64Url(new TextEncoder().encode(JSON.stringify(normalized)));\n  assertCharsetSafe(encoded);\n  return encoded;\n}\n\n/**\n * Resolve an engine-facing `_id` back to its normalized key components, in `keyFields` order.\n * Purely local — no remote call. Throws on any id this binding could not have synthesized —\n * INCLUDING every non-canonical ALIAS of a valid id (base64url trailing-bit variants,\n * JSON-whitespace variants, non-normalized verbatim forms such as an uppercase GUID): one remote\n * row answers to exactly ONE engine id, because row identity, URL canonicality, dedup keys and\n * id-based exclusion filters are all built on that equality. Enforced by re-synthesizing from the\n * resolved components and requiring byte-equality with the incoming id.\n */\nexport function resolveHttpApiKeyComponents(\n  binding: { keyFields: readonly HttpApiKeyField[] },\n  resourceId: string,\n): HttpApiKeyComponentValue[] {\n  if (resourceId.length === 0) {\n    throw new HttpApiResourceIdError('HTTP-API resource id must be a non-empty string.');\n  }\n\n  let components: HttpApiKeyComponentValue[];\n  if (httpApiBindingUsesVerbatimKey(binding)) {\n    components = [normalizeHttpApiKeyComponent(binding.keyFields[0], resourceId)];\n  } else {\n    assertCharsetSafe(resourceId);\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(new TextDecoder().decode(base64UrlToBytes(resourceId)));\n    } catch (error) {\n      throw new HttpApiResourceIdError(\n        `HTTP-API resource id '${resourceId}' is not a valid encoded composite key: ${describeCaughtError(error)}`,\n      );\n    }\n    if (!Array.isArray(parsed) || parsed.length !== binding.keyFields.length) {\n      throw new HttpApiResourceIdError(\n        `HTTP-API resource id '${resourceId}' decodes to ${Array.isArray(parsed) ? `${parsed.length} component(s)` : 'a non-array'} for a binding declaring ${binding.keyFields.length}.`,\n      );\n    }\n    components = binding.keyFields.map((keyField, index) => normalizeHttpApiKeyComponent(keyField, parsed[index]));\n  }\n\n  // Canonicality gate: re-synthesize and require byte-equality. Normalization is idempotent per\n  // codec, so a canonical id always round-trips to itself; any alias (dropped-bit base64url\n  // variant, whitespace-bearing JSON, '042' for an INTEGER key, 'ABC…' for a GUID key) differs\n  // here and is refused rather than silently adopted as a second name for the same row.\n  const canonical = synthesizeHttpApiResourceId(binding, components);\n  if (canonical !== resourceId) {\n    throw new HttpApiResourceIdError(\n      `HTTP-API resource id ${describeValue(resourceId)} is a non-canonical alias of ${describeValue(canonical)} and is refused: every remote row has exactly one engine id.`,\n    );\n  }\n  return components;\n}\n\n/** Runtime guard for the charset law. */\nexport function isCharsetSafeHttpApiResourceId(candidate: string): boolean {\n  return HTTP_API_RESOURCE_ID_CHARSET.test(candidate);\n}\n\nfunction assertCharsetSafe(candidate: string): void {\n  if (!isCharsetSafeHttpApiResourceId(candidate)) {\n    throw new HttpApiResourceIdError(\n      `HTTP-API resource id violates the charset law ${HTTP_API_RESOURCE_ID_CHARSET}: ${describeValue(candidate)}. `\n      + 'Ids must stay URL-unreserved — the frontend substitutes them into URLs without encoding, and websocket room names parse on \\':\\'.',\n    );\n  }\n}\n"]}