@wildo-ai/saas-backend-lib 1.1.2 → 1.1.3

package/dist/esm/monitoring/analytics/services/value-moment-definition-registry.backend.service.js

@@ -0,0 +1,199 @@
+/**
+ * The registered value-moment definitions, indexed by what can trigger them.
+ *
+ * Mirrors `MilestoneDefinitionRegistryBackendService` deliberately: same registration-at-startup
+ * shape, same trigger index, same fail-fast validation. The two vocabularies are distinct (a
+ * milestone is authored progression; a value moment is a measured behavioural moment with a role, a
+ * composition mode and typed signals) but the REGISTRY problem is identical, and solving it a second
+ * way would have produced two answers to "which definitions does this operation touch".
+ *
+ * Before #414 nothing registered these at all. The definitions were read once at startup, purely to
+ * warn about invalid feature references, and then discarded — so `ValueMomentEngineBackendService`
+ * had nothing to evaluate even if it had been implemented.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import 'reflect-metadata';
+import { injectable, inject } from 'inversify';
+import { ValueMomentMode, ValueMomentRole, ValueMomentScope, ValueSignalType } from '@wildo-ai/saas-models';
+import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
+/**
+ * The stable key of one signal WITHIN one moment.
+ *
+ * `ValueMomentMode.ALL` has to remember which signals have already fired, and it has to survive the
+ * definition being edited. An INDEX would not: inserting a signal at the front of the list silently
+ * re-points every recorded observation at a different signal. The key is derived from the signal's
+ * own content, so a signal that did not change keeps its identity, and one that did legitimately
+ * loses its recorded observation.
+ */
+export function valueSignalKey(signal) {
+    switch (signal.signalType) {
+        case ValueSignalType.RESOURCE_OPERATION:
+            return `${signal.signalType}:${signal.resourceType}:${signal.operation}`;
+        case ValueSignalType.RESOURCE_STATE:
+            return `${signal.signalType}:${signal.resourceType}`;
+        case ValueSignalType.VIEW_VISIT:
+            return `${signal.signalType}:${signal.contentType}:${signal.viewRef ?? '*'}`;
+        case ValueSignalType.FEATURE_ACCESS:
+            return `${signal.signalType}:${signal.featureId}`;
+        case ValueSignalType.CUSTOM_EVENT:
+            return `${signal.signalType}:${signal.eventName}`;
+    }
+}
+let ValueMomentDefinitionRegistryBackendService = class ValueMomentDefinitionRegistryBackendService {
+    logger;
+    definitions = new Map();
+    /** `<resourceType>:<operation>` → moments carrying a matching RESOURCE_OPERATION signal. */
+    operationIndex = new Map();
+    /** custom event name → moments carrying a matching CUSTOM_EVENT signal. */
+    eventIndex = new Map();
+    /**
+     * resource type → moments carrying a RESOURCE_STATE signal on it.
+     *
+     * Indexed by TYPE alone, not by operation: a state signal asks "how many rows match", and any
+     * write to that resource can change the answer. Keying it by operation would evaluate it only
+     * after a CREATE and miss the UPDATE that moved a row into the filter.
+     */
+    stateIndex = new Map();
+    logDebug;
+    constructor(logger) {
+        this.logger = logger;
+        this.logger.setDebugTypeLogging('ValueMomentDefinitionRegistry', false);
+        this.logDebug = this.logger.debugByType('ValueMomentDefinitionRegistry');
+    }
+    registerDefinitions(definitions) {
+        for (const definition of definitions) {
+            this.registerDefinition(definition);
+        }
+        this.logDebug(`Registered ${definitions.length} value moment definition(s)`);
+    }
+    registerDefinition(definition) {
+        const existing = this.definitions.get(definition.identifier);
+        if (existing) {
+            // Re-registration replaces, and every index entry for the OLD definition has to go with it —
+            // otherwise the operation that triggered the old one keeps evaluating a definition nobody can
+            // reach by identifier any more, and does it twice.
+            this.removeFromIndexes(existing);
+            this.logDebug(`Value moment ${definition.identifier} overridden`);
+        }
+        this.definitions.set(definition.identifier, definition);
+        for (const signal of definition.signals) {
+            if (signal.signalType === ValueSignalType.RESOURCE_OPERATION) {
+                const key = `${signal.resourceType}:${signal.operation}`;
+                this.operationIndex.set(key, [...(this.operationIndex.get(key) ?? []), definition]);
+            }
+            else if (signal.signalType === ValueSignalType.CUSTOM_EVENT) {
+                const key = signal.eventName;
+                this.eventIndex.set(key, [...(this.eventIndex.get(key) ?? []), definition]);
+            }
+            else if (signal.signalType === ValueSignalType.RESOURCE_STATE) {
+                const key = signal.resourceType;
+                this.stateIndex.set(key, [...(this.stateIndex.get(key) ?? []), definition]);
+            }
+        }
+    }
+    removeFromIndexes(definition) {
+        for (const index of [this.operationIndex, this.eventIndex, this.stateIndex]) {
+            for (const [key, list] of index) {
+                const filtered = list.filter(candidate => candidate.identifier !== definition.identifier);
+                if (filtered.length === 0)
+                    index.delete(key);
+                else
+                    index.set(key, filtered);
+            }
+        }
+    }
+    /**
+     * Fail-fast validation, run at startup after registration.
+     *
+     * Reports rather than throws. A milestone misconfiguration prevents boot because milestones gate
+     * feature unlocks; a value moment MEASURES and gates nothing, so refusing to start an application
+     * over a mis-declared metric would be a worse failure than the metric being wrong. The findings go
+     * to the log at WARN, which is where the startup summary of every other registry lands.
+     */
+    validateDefinitions() {
+        const findings = [];
+        for (const [identifier, definition] of this.definitions) {
+            if (definition.requires?.length) {
+                for (const required of definition.requires) {
+                    if (!this.definitions.has(required)) {
+                        findings.push(`Value moment '${identifier}': requires '${required}', which is not registered`);
+                    }
+                }
+            }
+            if (definition.beforeStage?.length) {
+                for (const stage of definition.beforeStage) {
+                    if (!this.definitions.has(stage)) {
+                        findings.push(`Value moment '${identifier}': beforeStage '${stage}' is not registered`);
+                    }
+                }
+            }
+            /*
+             * `ANY` fires on the first signal, so one signal is a complete declaration. `ALL` with one
+             * signal is the SAME moment written two ways — not wrong, but worth saying, because an author
+             * who wrote `ALL` was usually expecting to add more.
+             */
+            if (definition.mode === ValueMomentMode.ALL && definition.signals.length === 1) {
+                findings.push(`Value moment '${identifier}': mode ALL with a single signal behaves as ANY`);
+            }
+            if (definition.role === ValueMomentRole.ANTI_PATTERN && definition.scope === ValueMomentScope.ORGANIZATION) {
+                /*
+                 * An anti-pattern is a per-person frustration signal and is deliberately NOT persisted, so
+                 * an organization-scoped one measures "somebody in this tenant did the bad thing" with an
+                 * in-process cooldown shared across every member. That is almost certainly not what the
+                 * author meant.
+                 */
+                findings.push(`Value moment '${identifier}': ANTI_PATTERN at ORGANIZATION scope fires for any member and is not persisted`);
+            }
+        }
+        for (const finding of findings) {
+            this.logger.warn(`[ValueMomentRegistry] ${finding}`);
+        }
+        return findings;
+    }
+    getDefinition(identifier) {
+        return this.definitions.get(identifier);
+    }
+    getAllDefinitions() {
+        return [...this.definitions.values()];
+    }
+    /** Moments with a RESOURCE_OPERATION signal for this exact resource + operation. */
+    getMomentsForOperation(resourceType, operationIdentifier) {
+        return this.operationIndex.get(`${resourceType}:${operationIdentifier}`) ?? [];
+    }
+    /** Moments with a CUSTOM_EVENT signal for this event name. */
+    getMomentsForEvent(eventName) {
+        return this.eventIndex.get(eventName) ?? [];
+    }
+    /** Moments with a RESOURCE_STATE signal on this resource type. */
+    getMomentsForResourceState(resourceType) {
+        return this.stateIndex.get(resourceType) ?? [];
+    }
+    logStartupSummary() {
+        if (this.definitions.size === 0)
+            return;
+        const byRole = new Map();
+        for (const definition of this.definitions.values()) {
+            byRole.set(definition.role, (byRole.get(definition.role) ?? 0) + 1);
+        }
+        const summary = [...byRole.entries()].map(([role, count]) => `${role}=${count}`).join(', ');
+        this.logger.info(`[ValueMomentRegistry] ${this.definitions.size} value moment(s) registered (${summary})`);
+    }
+};
+ValueMomentDefinitionRegistryBackendService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
+    __metadata("design:paramtypes", [Function])
+], ValueMomentDefinitionRegistryBackendService);
+export { ValueMomentDefinitionRegistryBackendService };
+//# sourceMappingURL=value-moment-definition-registry.backend.service.js.map

package/dist/esm/monitoring/analytics/services/value-moment-definition-registry.backend.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-moment-definition-registry.backend.service.js","sourceRoot":"","sources":["../../../../../../src/monitoring/analytics/services/value-moment-definition-registry.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The registered value-moment definitions, indexed by what can trigger them.\n *\n * Mirrors `MilestoneDefinitionRegistryBackendService` deliberately: same registration-at-startup\n * shape, same trigger index, same fail-fast validation. The two vocabularies are distinct (a\n * milestone is authored progression; a value moment is a measured behavioural moment with a role, a\n * composition mode and typed signals) but the REGISTRY problem is identical, and solving it a second\n * way would have produced two answers to \"which definitions does this operation touch\".\n *\n * Before #414 nothing registered these at all. The definitions were read once at startup, purely to\n * warn about invalid feature references, and then discarded — so `ValueMomentEngineBackendService`\n * had nothing to evaluate even if it had been implemented.\n */\n\nimport 'reflect-metadata';\nimport { injectable, inject } from 'inversify';\nimport { ValueMomentMode, ValueMomentRole, ValueMomentScope, ValueSignalType } from '@wildo-ai/saas-models';\nimport type { ValueMoment, ValueSignal } from '@wildo-ai/saas-models';\n\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';\n\n/**\n * The stable key of one signal WITHIN one moment.\n *\n * `ValueMomentMode.ALL` has to remember which signals have already fired, and it has to survive the\n * definition being edited. An INDEX would not: inserting a signal at the front of the list silently\n * re-points every recorded observation at a different signal. The key is derived from the signal's\n * own content, so a signal that did not change keeps its identity, and one that did legitimately\n * loses its recorded observation.\n */\nexport function valueSignalKey(signal: ValueSignal): string {\n  switch (signal.signalType) {\n    case ValueSignalType.RESOURCE_OPERATION:\n      return `${signal.signalType}:${signal.resourceType}:${signal.operation}`;\n    case ValueSignalType.RESOURCE_STATE:\n      return `${signal.signalType}:${signal.resourceType}`;\n    case ValueSignalType.VIEW_VISIT:\n      return `${signal.signalType}:${signal.contentType}:${signal.viewRef ?? '*'}`;\n    case ValueSignalType.FEATURE_ACCESS:\n      return `${signal.signalType}:${signal.featureId}`;\n    case ValueSignalType.CUSTOM_EVENT:\n      return `${signal.signalType}:${signal.eventName}`;\n  }\n}\n\n@injectable()\nexport class ValueMomentDefinitionRegistryBackendService {\n  private definitions: Map<string, ValueMoment> = new Map();\n  /** `<resourceType>:<operation>` → moments carrying a matching RESOURCE_OPERATION signal. */\n  private operationIndex: Map<string, ValueMoment[]> = new Map();\n  /** custom event name → moments carrying a matching CUSTOM_EVENT signal. */\n  private eventIndex: Map<string, ValueMoment[]> = new Map();\n  /**\n   * resource type → moments carrying a RESOURCE_STATE signal on it.\n   *\n   * Indexed by TYPE alone, not by operation: a state signal asks \"how many rows match\", and any\n   * write to that resource can change the answer. Keying it by operation would evaluate it only\n   * after a CREATE and miss the UPDATE that moved a row into the filter.\n   */\n  private stateIndex: Map<string, ValueMoment[]> = new Map();\n\n  private logDebug: (message: string, context?: Record<string, unknown>) => void;\n\n  constructor(\n    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,\n  ) {\n    this.logger.setDebugTypeLogging('ValueMomentDefinitionRegistry', false);\n    this.logDebug = this.logger.debugByType('ValueMomentDefinitionRegistry');\n  }\n\n  public registerDefinitions(definitions: ValueMoment[]): void {\n    for (const definition of definitions) {\n      this.registerDefinition(definition);\n    }\n    this.logDebug(`Registered ${definitions.length} value moment definition(s)`);\n  }\n\n  private registerDefinition(definition: ValueMoment): void {\n    const existing = this.definitions.get(definition.identifier);\n    if (existing) {\n      // Re-registration replaces, and every index entry for the OLD definition has to go with it —\n      // otherwise the operation that triggered the old one keeps evaluating a definition nobody can\n      // reach by identifier any more, and does it twice.\n      this.removeFromIndexes(existing);\n      this.logDebug(`Value moment ${definition.identifier} overridden`);\n    }\n    this.definitions.set(definition.identifier, definition);\n\n    for (const signal of definition.signals) {\n      if (signal.signalType === ValueSignalType.RESOURCE_OPERATION) {\n        const key = `${signal.resourceType}:${signal.operation}`;\n        this.operationIndex.set(key, [...(this.operationIndex.get(key) ?? []), definition]);\n      } else if (signal.signalType === ValueSignalType.CUSTOM_EVENT) {\n        const key = signal.eventName;\n        this.eventIndex.set(key, [...(this.eventIndex.get(key) ?? []), definition]);\n      } else if (signal.signalType === ValueSignalType.RESOURCE_STATE) {\n        const key = signal.resourceType;\n        this.stateIndex.set(key, [...(this.stateIndex.get(key) ?? []), definition]);\n      }\n    }\n  }\n\n  private removeFromIndexes(definition: ValueMoment): void {\n    for (const index of [this.operationIndex, this.eventIndex, this.stateIndex]) {\n      for (const [key, list] of index) {\n        const filtered = list.filter(candidate => candidate.identifier !== definition.identifier);\n        if (filtered.length === 0) index.delete(key);\n        else index.set(key, filtered);\n      }\n    }\n  }\n\n  /**\n   * Fail-fast validation, run at startup after registration.\n   *\n   * Reports rather than throws. A milestone misconfiguration prevents boot because milestones gate\n   * feature unlocks; a value moment MEASURES and gates nothing, so refusing to start an application\n   * over a mis-declared metric would be a worse failure than the metric being wrong. The findings go\n   * to the log at WARN, which is where the startup summary of every other registry lands.\n   */\n  public validateDefinitions(): string[] {\n    const findings: string[] = [];\n\n    for (const [identifier, definition] of this.definitions) {\n      if (definition.requires?.length) {\n        for (const required of definition.requires) {\n          if (!this.definitions.has(required)) {\n            findings.push(`Value moment '${identifier}': requires '${required}', which is not registered`);\n          }\n        }\n      }\n      if (definition.beforeStage?.length) {\n        for (const stage of definition.beforeStage) {\n          if (!this.definitions.has(stage)) {\n            findings.push(`Value moment '${identifier}': beforeStage '${stage}' is not registered`);\n          }\n        }\n      }\n      /*\n       * `ANY` fires on the first signal, so one signal is a complete declaration. `ALL` with one\n       * signal is the SAME moment written two ways — not wrong, but worth saying, because an author\n       * who wrote `ALL` was usually expecting to add more.\n       */\n      if (definition.mode === ValueMomentMode.ALL && definition.signals.length === 1) {\n        findings.push(`Value moment '${identifier}': mode ALL with a single signal behaves as ANY`);\n      }\n      if (definition.role === ValueMomentRole.ANTI_PATTERN && definition.scope === ValueMomentScope.ORGANIZATION) {\n        /*\n         * An anti-pattern is a per-person frustration signal and is deliberately NOT persisted, so\n         * an organization-scoped one measures \"somebody in this tenant did the bad thing\" with an\n         * in-process cooldown shared across every member. That is almost certainly not what the\n         * author meant.\n         */\n        findings.push(`Value moment '${identifier}': ANTI_PATTERN at ORGANIZATION scope fires for any member and is not persisted`);\n      }\n    }\n\n    for (const finding of findings) {\n      this.logger.warn(`[ValueMomentRegistry] ${finding}`);\n    }\n    return findings;\n  }\n\n  public getDefinition(identifier: string): ValueMoment | undefined {\n    return this.definitions.get(identifier);\n  }\n\n  public getAllDefinitions(): ValueMoment[] {\n    return [...this.definitions.values()];\n  }\n\n  /** Moments with a RESOURCE_OPERATION signal for this exact resource + operation. */\n  public getMomentsForOperation(resourceType: string, operationIdentifier: string): ValueMoment[] {\n    return this.operationIndex.get(`${resourceType}:${operationIdentifier}`) ?? [];\n  }\n\n  /** Moments with a CUSTOM_EVENT signal for this event name. */\n  public getMomentsForEvent(eventName: string): ValueMoment[] {\n    return this.eventIndex.get(eventName) ?? [];\n  }\n\n  /** Moments with a RESOURCE_STATE signal on this resource type. */\n  public getMomentsForResourceState(resourceType: string): ValueMoment[] {\n    return this.stateIndex.get(resourceType) ?? [];\n  }\n\n  public logStartupSummary(): void {\n    if (this.definitions.size === 0) return;\n    const byRole = new Map<ValueMomentRole, number>();\n    for (const definition of this.definitions.values()) {\n      byRole.set(definition.role, (byRole.get(definition.role) ?? 0) + 1);\n    }\n    const summary = [...byRole.entries()].map(([role, count]) => `${role}=${count}`).join(', ');\n    this.logger.info(`[ValueMomentRegistry] ${this.definitions.size} value moment(s) registered (${summary})`);\n  }\n}\n"]}

package/dist/esm/monitoring/analytics/services/value-moment-engine.backend.service.d.ts

@@ -1,22 +1,121 @@
-import { LoggerService } from '../../../monitoring/logger/services/logger.service';
+/**
+ * Value Moment Engine — evaluates value-moment signals and records what a scope has achieved.
+ *
+ * ## What this was until 2026-09-08 (#414)
+ *
+ * Placeholders. `evaluateOperationSignal` logged, `markAchieved` logged, `getAchievedMoments`
+ * returned an empty array unconditionally, and the handler registry beside it had no registration
+ * path and was never invoked. Meanwhile `analytics.persistence.backendSync` and `backendEvaluation`
+ * both default to TRUE, so an application was promised cross-device persistence and authoritative
+ * evaluation, received neither, and was answered 200.
+ *
+ * ## Where the state lives, and why not in a resource of its own
+ *
+ * `valueMomentsAchieved` on the PROGRESSION STATE row — the same per-scope row milestones use. That
+ * row already carries the `PersonalDataCategory.USAGE` classification, the `RedactionType.RESET`
+ * erasure treatment, the subject-export provenance and the `onParentCreate`/`onParentDelete`
+ * lifecycle that a per-user behavioural record owes. A second resource would have re-declared all of
+ * them for the same shape of data.
+ *
+ * ## Concurrency
+ *
+ * Every write is a compare-and-swap through `atomicGuardedMutation`, guarded on the moment NOT being
+ * achieved. Two operations in the same instant can both observe "not yet achieved"; without the
+ * guard both would write, both would invoke the handler, and a TTFV would be recorded twice with
+ * different timestamps. This is the same guard the milestone evaluator uses, for the same reason.
+ *
+ * ## What ANTI_PATTERN does differently
+ *
+ * `ValueMomentRole.ANTI_PATTERN` is declared as NOT persisted: it re-fires on a cooldown rather than
+ * being achieved once. So it writes nothing here and its cooldown is in-process — in a multi-instance
+ * deployment each instance keeps its own, which is what "not persisted" means rather than a defect.
+ */
+import 'reflect-metadata';
+import type { LoggerService } from '../../../monitoring/logger/services/logger.service';
+import type { RepositoriesRegistryHandlerBackendService } from '../../../base-classes/services/repositories/repositories-registry-handler.backend.service';
+import type { ProgressionStateStoreBackendService } from '../../../guidance/services/progression-state-store.backend.service';
 import { ValueMomentHandlerRegistryBackendService } from './value-moment-handler-registry.backend.service';
+import type { ValueMomentDefinitionRegistryBackendService } from './value-moment-definition-registry.backend.service';
+/** The identity a signal is evaluated against — either id may be absent. */
+export interface ValueMomentPrincipal {
+    userId?: string;
+    organizationId?: string;
+}
+/**
+ * The outcome of a write, so a caller can answer honestly.
+ *
+ * The controller answered 200 for a discarded write because the engine returned `void` and there was
+ * nothing to report. Every write path now says which of the four things happened.
+ */
+export declare enum ValueMomentWriteOutcome {
+    /** Newly achieved and persisted. */
+    RECORDED = "recorded",
+    /** Already achieved — the compare-and-swap declined, which is success, not failure. */
+    ALREADY_ACHIEVED = "already_achieved",
+    /** The scope this moment measures is not present on the execution (no user, or no organization). */
+    SCOPE_UNAVAILABLE = "scope_unavailable",
+    /** The store could not be reached. The caller must NOT report success. */
+    NOT_PERSISTED = "not_persisted"
+}
 export declare class ValueMomentEngineBackendService {
     private logger;
     private handlerRegistry;
-    constructor(logger: LoggerService, handlerRegistry: ValueMomentHandlerRegistryBackendService);
+    private definitionRegistry;
+    private progressionStateStore;
+    private repositoriesRegistry;
+    /**
+     * Last fire time per `<scope>:<scopeId>:<momentIdentifier>` for ANTI_PATTERN moments only.
+     *
+     * In-process on purpose — see the class docstring. Bounded by the number of anti-pattern
+     * definitions times active scopes, which is the same population the definitions already bound.
+     */
+    private readonly antiPatternLastFiredAt;
+    private logDebug;
+    constructor(logger: LoggerService, handlerRegistry: ValueMomentHandlerRegistryBackendService, definitionRegistry: ValueMomentDefinitionRegistryBackendService, progressionStateStore: ProgressionStateStoreBackendService, repositoriesRegistry: RepositoriesRegistryHandlerBackendService);
     /**
-     * Evaluate an operation signal to determine if any value moments should be triggered.
-     * Placeholder — full implementation deferred.
+     * Evaluate an operation against every value moment carrying a matching RESOURCE_OPERATION signal.
+     *
+     * Never throws. Runs fire-and-forget after the operation's response has been decided, so a failure
+     * here must not surface as an error on a request that already succeeded — the same posture the
+     * milestone evaluator takes.
      */
     evaluateOperationSignal(params: {
         resourceType: string;
         operationIdentifier: string;
         operationResult: unknown;
-        executionContext: unknown;
+        principal: ValueMomentPrincipal;
     }): Promise<void>;
     /**
-     * Emit a generic analytics signal for downstream processing.
-     * Placeholder — full implementation deferred.
+     * A RESOURCE_OPERATION signal's optional field filter.
+     *
+     * SHALLOW EQUALITY over primitives, which is exactly what `ValueSignal_FilterSchema` documents
+     * ("no nested objects or arrays"). A filter whose field is absent from the result does NOT match:
+     * the signal asked for a specific state and the evidence does not show it, so treating absence as
+     * a match would fire moments the author narrowed on purpose.
+     */
+    private operationSignalMatches;
+    /**
+     * RESOURCE_STATE signals — "this scope owns at least N rows of this type matching this filter".
+     *
+     * This is the half `analytics.persistence.backendEvaluation` is specifically about: its own
+     * docstring says the backend evaluates RESOURCE_STATE signals AUTHORITATIVELY, while the frontend
+     * "does optimistic cached count queries". Before #414 neither happened on the backend at all.
+     *
+     * Re-counted on any write to the resource type rather than on a specific operation, because a
+     * state signal asks about the CURRENT population: a create, an update that moves a row into the
+     * filter, and a delete that moves one out all change the answer.
+     *
+     * The count runs through the INFRASTRUCTURE door deliberately. It is a system evaluation with no
+     * request principal — the achieving user is not necessarily reading their own rows through an
+     * authorized operation — so it must not borrow request-tier authorization. The scope filter is
+     * applied HERE, by this method, which is what that door requires of its callers.
+     */
+    private evaluateResourceStateSignals;
+    /**
+     * A generic analytics signal — the CUSTOM_EVENT half of the vocabulary.
+     *
+     * `context` names the scope this event belongs to, because a custom event is emitted by code that
+     * knows whose journey it is measuring and the engine cannot recover that from the event name.
      */
     emitSignal(signal: {
         signalType: string;
@@ -26,16 +125,53 @@ export declare class ValueMomentEngineBackendService {
         entityId: string;
     }): Promise<void>;
     /**
-     * Retrieve achieved moments for a given execution context.
-     * Placeholder — returns empty array until persistence is implemented.
+     * Record that one of a moment's signals fired, and achieve the moment if that completes it.
+     *
+     * `ANY` completes on any signal; `ALL` completes when every signal key has been observed. The
+     * observation itself is persisted for both, so an `ALL` moment accumulates across requests — which
+     * is the only reason `ALL` can mean anything on a stateless backend.
+     */
+    private observeSignal;
+    /**
+     * ANTI_PATTERN: fire the handler, persist nothing, respect the cooldown.
+     *
+     * The role's own contract. It measures a recurring frustration rather than a one-time achievement,
+     * so there is no "achieved" state to record and re-firing is the point.
+     */
+    private fireAntiPattern;
+    /**
+     * `requires` gates a moment until its prerequisites are achieved; `beforeStage` SUPPRESSES it once
+     * any named stage is. Both read the same persisted map, so a moment whose stage was reached in an
+     * earlier request stays suppressed.
+     */
+    private prerequisitesMet;
+    private resolveTarget;
+    /**
+     * Invoke the moment's registered backend handler, if it declared one.
+     *
+     * Failures are logged and swallowed: the moment IS achieved and the record is already written, so
+     * a handler that throws must not make the achievement look like it did not happen. The registry
+     * warns on its own when a declared handler was never registered.
+     */
+    private invokeAchievementHandler;
+    /**
+     * The moments this principal has achieved.
+     *
+     * Returns the USER scope's moments, plus the ORGANIZATION scope's when the execution carries one —
+     * both are "what this person has reached", and the frontend's achieved-set is not scope-split.
      */
-    getAchievedMoments(_executionContext: unknown): Promise<{
+    getAchievedMoments(principal: ValueMomentPrincipal): Promise<{
         momentIdentifier: string;
+        achievedAt: Date;
     }[]>;
     /**
-     * Mark a value moment as achieved.
-     * Placeholder — logs and returns until persistence is implemented.
+     * Record a moment as achieved directly — the frontend's `backendSync` path, where the frontend
+     * evaluated a signal the backend cannot see (a view visit, a feature access) and reports it.
+     *
+     * The scope comes from the DEFINITION when the moment is registered, and from the caller only when
+     * it is not: an application may sync a moment the backend does not know about, and refusing it
+     * would lose the frontend's evaluation entirely.
      */
-    markAchieved(momentIdentifier: string, _executionContext: unknown, scope?: string): Promise<void>;
+    markAchieved(momentIdentifier: string, principal: ValueMomentPrincipal, requestedScope?: string): Promise<ValueMomentWriteOutcome>;
 }
 //# sourceMappingURL=value-moment-engine.backend.service.d.ts.map

package/dist/esm/monitoring/analytics/services/value-moment-engine.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"value-moment-engine.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/monitoring/analytics/services/value-moment-engine.backend.service.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAC7F,OAAO,EAAE,wCAAwC,EAAE,MAAM,iDAAiD,CAAC;AAE3G,qBACa,+BAA+B;IAEL,OAAO,CAAC,MAAM;IACM,OAAO,CAAC,eAAe;gBADnC,MAAM,EAAE,aAAa,EACD,eAAe,EAAE,wCAAwC;IAG1H;;;OAGG;IACG,uBAAuB,CAAC,MAAM,EAAE;QACpC,YAAY,EAAE,MAAM,CAAC;QACrB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,eAAe,EAAE,OAAO,CAAC;QACzB,gBAAgB,EAAE,OAAO,CAAC;KAC3B,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjB;;;OAGG;IACG,UAAU,CACd,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EACjD,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAC3C,OAAO,CAAC,IAAI,CAAC;IAIhB;;;OAGG;IACG,kBAAkB,CAAC,iBAAiB,EAAE,OAAO,GAAG,OAAO,CAAC;QAAE,gBAAgB,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAI7F;;;OAGG;IACG,YAAY,CAAC,gBAAgB,EAAE,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGxG"}
+{"version":3,"file":"value-moment-engine.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/monitoring/analytics/services/value-moment-engine.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,kBAAkB,CAAC;AAa1B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,KAAK,EAAE,yCAAyC,EAAE,MAAM,qGAAqG,CAAC;AACrK,OAAO,KAAK,EAAE,mCAAmC,EAAE,MAAM,8EAA8E,CAAC;AACxI,OAAO,EAAE,wCAAwC,EAAE,MAAM,iDAAiD,CAAC;AAE3G,OAAO,KAAK,EAAE,2CAA2C,EAAE,MAAM,oDAAoD,CAAC;AAKtH,4EAA4E;AAC5E,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,oBAAY,uBAAuB;IACjC,oCAAoC;IACpC,QAAQ,aAAa;IACrB,uFAAuF;IACvF,gBAAgB,qBAAqB;IACrC,oGAAoG;IACpG,iBAAiB,sBAAsB;IACvC,0EAA0E;IAC1E,aAAa,kBAAkB;CAChC;AAOD,qBACa,+BAA+B;IAYL,OAAO,CAAC,MAAM;IACM,OAAO,CAAC,eAAe;IACpB,OAAO,CAAC,kBAAkB;IAClC,OAAO,CAAC,qBAAqB;IAChB,OAAO,CAAC,oBAAoB;IAf7F;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAA6B;IAEpE,OAAO,CAAC,QAAQ,CAA+D;gBAGlC,MAAM,EAAE,aAAa,EACD,eAAe,EAAE,wCAAwC,EACtD,kBAAkB,EAAE,2CAA2C,EACvE,qBAAqB,EAAE,mCAAmC,EAC7C,oBAAoB,EAAE,yCAAyC;IAUxI;;;;;;OAMG;IACU,uBAAuB,CAAC,MAAM,EAAE;QAC3C,YAAY,EAAE,MAAM,CAAC;QACrB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,eAAe,EAAE,OAAO,CAAC;QACzB,SAAS,EAAE,oBAAoB,CAAC;KACjC,GAAG,OAAO,CAAC,IAAI,CAAC;IA2CjB;;;;;;;OAOG;IACH,OAAO,CAAC,sBAAsB;IAO9B;;;;;;;;;;;;;;;OAeG;YACW,4BAA4B;IA4C1C;;;;;OAKG;IACU,UAAU,CACrB,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EACjD,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAC3C,OAAO,CAAC,IAAI,CAAC;IA2BhB;;;;;;OAMG;YACW,aAAa;IAsE3B;;;;;OAKG;YACW,eAAe;IAgB7B;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,aAAa;IASrB;;;;;;OAMG;YACW,wBAAwB;IAyBtC;;;;;OAKG;IACU,kBAAkB,CAAC,SAAS,EAAE,oBAAoB,GAAG,OAAO,CAAC;QAAE,gBAAgB,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,IAAI,CAAA;KAAE,EAAE,CAAC;IAe3H;;;;;;;OAOG;IACU,YAAY,CACvB,gBAAgB,EAAE,MAAM,EACxB,SAAS,EAAE,oBAAoB,EAC/B,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,uBAAuB,CAAC;CA2CpC"}