@dsh-enhanced/preference-learning 0.1.7 → 0.1.14

package/lib/service.js

@@ -1,6 +1,9 @@
+import { createHash, randomUUID } from 'node:crypto';
 import { Context, Service } from '@deepseek-ai/cordis';
 import Schema from '@deepseek-ai/schemastery';
-import { PreferenceStore, canonicalPreferenceScope } from './store.js';
+import { PREFERENCE_MEMORY_PROMOTION_PROTOCOL, brandPreferenceMemoryPromotionProducer, unbrandPreferenceMemoryPromotionProducer, validatePreferenceMemoryPromotionCancellationReceipt, validatePreferenceMemoryPromotionResult, validatePreferenceMemoryPromotionSubmissionReceipt, } from '@dsh-enhanced/assistant-growth-contract';
+import { DELIVERY_PREFERENCE_PROJECTION_PROTOCOL, isTrustedDeliveryPreferenceProducer, } from '@dsh-enhanced/assistant-delivery';
+import { PreferenceStore, PreferenceStoreError, canonicalPreferenceScope } from './store.js';
 import { registerPreferenceTools } from './tools.js';
 const configSchema = Schema.object({
     enabled: Schema.boolean().default(true),
@@ -8,6 +11,8 @@ const configSchema = Schema.object({
     signalTtlMs: Schema.number().step(1).min(86_400_000).max(31_536_000_000).default(7_776_000_000),
     hypothesisTtlMs: Schema.number().step(1).min(3_600_000).max(2_592_000_000).default(2_592_000_000),
     minSignalsForActivation: Schema.number().step(1).min(2).max(20).default(2),
+    minBehavioralSignalsForActivation: Schema.number().step(1).min(4).max(20).default(6),
+    autonomousT1Enabled: Schema.boolean().default(true),
     minConfidenceBps: Schema.number().step(1).min(6_000).max(9_500).default(7_500),
     maxContradictionBps: Schema.number().step(1).min(0).max(4_000).default(2_500),
     maxActiveOverlays: Schema.number().step(1).min(1).max(8).default(6),
@@ -15,6 +20,7 @@ const configSchema = Schema.object({
     maxOverlayBytes: Schema.number().step(1).min(256).max(2_048).default(2_048),
     maintenanceIntervalMs: Schema.number().step(1).min(60_000).max(86_400_000).default(3_600_000),
     maintenanceBatchSize: Schema.number().step(1).min(1).max(5_000).default(500),
+    promotionReconcileLimit: Schema.number().step(1).min(1).max(1_000).default(50),
 });
 export class PreferenceLearningError extends Error {
     code;
@@ -27,15 +33,86 @@ export class PreferenceLearningError extends Error {
 function decisionError(decision) {
     return new PreferenceLearningError('policy-denied', `preference access denied: ${decision.reasonCode}`);
 }
+/** Fixed Policy subject used by the non-model supervised-growth runbook. */
+export const HOST_RECOVERY_BACKGROUND_ID = 'dsh-enhanced-assistant-recovery';
+const preferenceHostScopeBrand = Symbol('preference-learning.host-scope');
+export function canonicalPreferenceHostScope(input) {
+    try {
+        const { scope } = canonicalPreferenceScope(input);
+        const branded = { workspace: scope.workspace, preset: scope.preset };
+        Object.defineProperty(branded, preferenceHostScopeBrand, {
+            value: true, enumerable: false, configurable: false, writable: false,
+        });
+        return Object.freeze(branded);
+    }
+    catch {
+        throw new PreferenceLearningError('invalid-scope', 'Host preference scope is invalid');
+    }
+}
+function hostText(value, label, maxBytes, code = 'invalid-input') {
+    if (typeof value !== 'string') {
+        throw new PreferenceLearningError(code, `${label} must be a string`);
+    }
+    const normalized = value.normalize('NFC').trim();
+    if (normalized === '' || Buffer.byteLength(normalized, 'utf8') > maxBytes || hasControl(normalized)) {
+        throw new PreferenceLearningError(code, `${label} is invalid`);
+    }
+    return normalized;
+}
+function hasControl(value) {
+    for (const character of value) {
+        const codePoint = character.codePointAt(0);
+        if (codePoint <= 0x1f || codePoint === 0x7f)
+            return true;
+    }
+    return false;
+}
+function exactHostScope(input) {
+    if (typeof input !== 'object' || input === null || !Object.isFrozen(input)
+        || input[preferenceHostScopeBrand] !== true) {
+        throw new PreferenceLearningError('invalid-scope', 'Host preference operations require a canonical immutable scope');
+    }
+    const canonical = canonicalPreferenceHostScope(input);
+    if (canonical.workspace !== input.workspace || canonical.preset !== input.preset) {
+        throw new PreferenceLearningError('invalid-scope', 'Host preference scope is not canonical');
+    }
+    return input;
+}
+function isDeliveryPreferenceProducer(value) {
+    return isTrustedDeliveryPreferenceProducer(value)
+        && typeof value
+            .trustedPreferenceProducerGeneration === 'function'
+        && typeof value.registerTrustedPreferenceSink === 'function'
+        && typeof value.currentPreferenceTurn === 'function'
+        && typeof value.preferencePrincipalForAgent === 'function';
+}
+function registrationOwnedByPersonalMemory(registration) {
+    try {
+        return typeof registration.owner === 'object' && registration.owner !== null
+            && typeof registration.owner.ownsPreferencePromotionSourceRegistration === 'function'
+            && registration.owner.ownsPreferencePromotionSourceRegistration(registration);
+    }
+    catch {
+        return false;
+    }
+}
 export class PreferenceLearningService extends Service {
     static Config = configSchema;
     static inject = ['assistantPolicy', 'systemPrompt'];
     store;
     policy;
     config;
+    activeDeliveryRegistrations = new WeakSet();
+    memoryPromotionProducerGeneration = `preference-${randomUUID()}`;
+    /** Re-entrancy guard only; durable ownership and retry state remain in SQLite. */
+    memoryPromotionReconcileRunning = false;
+    memoryPromotionReconcileScheduled = false;
+    memoryPromotionBinding;
+    deliveryBinding;
     active = true;
     constructor(ctx, input, options = {}) {
         super(ctx, 'assistantPreferenceLearning');
+        brandPreferenceMemoryPromotionProducer(this);
         try {
             this.config = configSchema(input);
         }
@@ -55,11 +132,16 @@ export class PreferenceLearningService extends Service {
             signalTtlMs: this.config.signalTtlMs,
             hypothesisTtlMs: this.config.hypothesisTtlMs,
             minSignalsForActivation: this.config.minSignalsForActivation,
+            minBehavioralSignalsForActivation: this.config.minBehavioralSignalsForActivation,
             minConfidenceBps: this.config.minConfidenceBps,
             maxContradictionBps: this.config.maxContradictionBps,
             maxActiveOverlays: this.config.maxActiveOverlays,
             maxReviewHypotheses: this.config.maxReviewHypotheses,
             maxOverlayBytes: this.config.maxOverlayBytes,
+            minSignalsForPromotion: 3,
+            minConfidenceBpsForPromotion: 8_500,
+            maxContradictionBpsForPromotion: 1_500,
+            promotionProposalTtlMs: Math.min(this.config.hypothesisTtlMs, 604_800_000),
         });
         // Runtime context is re-evaluated before every model step. The AgentLoop
         // projection replaces or clears its prior snapshot, so rollback, expiry,
@@ -69,13 +151,15 @@ export class PreferenceLearningService extends Service {
             order: 250,
             text: ({ agent }) => this.dynamicOverlay(agent),
         });
+        const currentDelivery = ctx.get('assistantDelivery');
+        if (isDeliveryPreferenceProducer(currentDelivery)) {
+            this.bindDeliveryProducer(currentDelivery);
+        }
         ctx.inject(['assistantDelivery'], deliveryCtx => {
-            if (!this.config.enabled)
-                return;
             const delivery = deliveryCtx.get('assistantDelivery');
-            if (delivery === undefined || typeof delivery.subscribePreferenceFeedback !== 'function')
+            if (!isDeliveryPreferenceProducer(delivery))
                 return;
-            return delivery.subscribePreferenceFeedback(events => this.appendDeliveryFeedbackBatch(events));
+            return this.bindDeliveryProducer(delivery);
         });
         const registeredTools = ctx.get('tools');
         const disposeCurrentTools = registeredTools === undefined
@@ -88,11 +172,19 @@ export class PreferenceLearningService extends Service {
             return registerPreferenceTools(tools, this);
         });
         this.store.maintain(this.config.maintenanceBatchSize);
+        if (this.config.enabled && this.config.autonomousT1Enabled) {
+            this.store.activateReadyScopes(this.config.maintenanceBatchSize);
+        }
         const maintenanceTimer = setInterval(() => {
             if (!this.active)
                 return;
             try {
                 this.store.maintain(this.config.maintenanceBatchSize);
+                if (this.config.enabled && this.config.autonomousT1Enabled) {
+                    this.store.activateReadyScopes(this.config.maintenanceBatchSize);
+                }
+                if (this.memoryPromotionBinding !== undefined)
+                    this.reconcileMemoryPromotions();
             }
             catch {
                 ctx.logger.warn('preference-learning: bounded retention maintenance failed');
@@ -101,11 +193,150 @@ export class PreferenceLearningService extends Service {
         maintenanceTimer.unref();
         ctx.effect(() => () => {
             this.active = false;
+            unbrandPreferenceMemoryPromotionProducer(this);
             clearInterval(maintenanceTimer);
+            this.deliveryBinding?.dispose();
+            this.deliveryBinding = undefined;
+            this.memoryPromotionBinding?.dispose();
+            this.memoryPromotionBinding = undefined;
             disposeCurrentTools?.();
             this.store.close();
         }, 'preference-learning.database');
     }
+    trustedMemoryPromotionProducerGeneration() {
+        this.assertActive();
+        return this.memoryPromotionProducerGeneration;
+    }
+    /** Accept one exact Memory-owned, process-local bidirectional registration. */
+    registerTrustedMemoryPromotionResultSink(registration) {
+        this.assertActive();
+        if (registration.protocol !== PREFERENCE_MEMORY_PROMOTION_PROTOCOL
+            || registration.producer !== 'personal-memory'
+            || registration.sourceGeneration !== this.memoryPromotionProducerGeneration
+            || typeof registration.sinkGeneration !== 'string'
+            || registration.sinkGeneration.normalize('NFC').trim() !== registration.sinkGeneration
+            || registration.sinkGeneration === ''
+            || Buffer.byteLength(registration.sinkGeneration, 'utf8') > 200
+            || typeof registration.propose !== 'function'
+            || typeof registration.cancelPromotion !== 'function'
+            || typeof registration.listTerminalResults !== 'function'
+            || typeof registration.acknowledgeTerminalResult !== 'function'
+            || !registrationOwnedByPersonalMemory(registration)) {
+            throw new PreferenceLearningError('unattested-signal', 'trusted Memory promotion registration is invalid');
+        }
+        const current = this.memoryPromotionBinding;
+        if (current !== undefined) {
+            if (current.registration === registration)
+                return current.dispose;
+            throw new PreferenceLearningError('unattested-signal', 'trusted Memory promotion sink is already registered');
+        }
+        const token = Symbol('preference-learning.memory-promotion');
+        let live = true;
+        const dispose = () => {
+            if (!live)
+                return;
+            live = false;
+            if (this.memoryPromotionBinding?.token === token)
+                this.memoryPromotionBinding = undefined;
+        };
+        this.memoryPromotionBinding = Object.freeze({ token, registration, dispose });
+        this.reconcileMemoryPromotions();
+        return dispose;
+    }
+    /**
+     * Bounded durable producer drain. Failures stay in retry_wait; one malformed
+     * or unavailable Memory row never drops the remaining outbox.
+     */
+    reconcileMemoryPromotions(limit = this.config.promotionReconcileLimit) {
+        this.assertActive();
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1_000) {
+            throw new PreferenceLearningError('invalid-input', 'promotion reconcile limit is invalid');
+        }
+        const binding = this.memoryPromotionBinding;
+        if (binding === undefined)
+            return Object.freeze({ submitted: 0, cancelled: 0, projected: 0 });
+        if (this.memoryPromotionReconcileRunning) {
+            return Object.freeze({ submitted: 0, cancelled: 0, projected: 0 });
+        }
+        this.memoryPromotionReconcileRunning = true;
+        let submitted = 0;
+        let cancelled = 0;
+        let projected = 0;
+        const current = () => this.memoryPromotionBinding?.token === binding.token
+            && binding.registration.sourceGeneration === this.memoryPromotionProducerGeneration
+            && registrationOwnedByPersonalMemory(binding.registration);
+        try {
+            for (const request of this.store.listPendingMemoryPromotionCancellations(limit)) {
+                if (!current())
+                    return Object.freeze({ submitted, cancelled, projected });
+                try {
+                    const receipt = validatePreferenceMemoryPromotionCancellationReceipt(binding.registration.cancelPromotion(request), request);
+                    this.store.settleMemoryPromotionCancellation({ request, receipt });
+                    cancelled += 1;
+                }
+                catch (error) {
+                    this.store.settleMemoryPromotionCancellation({
+                        request,
+                        retryError: this.promotionFailureCode(error),
+                    });
+                }
+            }
+            for (const entry of this.store.listPendingMemoryPromotions(limit)) {
+                if (!current())
+                    return Object.freeze({ submitted, cancelled, projected });
+                try {
+                    const receipt = validatePreferenceMemoryPromotionSubmissionReceipt(binding.registration.propose(entry.request), entry.request);
+                    this.store.settleMemoryPromotionSubmission({ request: entry.request, receipt });
+                    submitted += 1;
+                }
+                catch (error) {
+                    this.store.settleMemoryPromotionSubmission({
+                        request: entry.request,
+                        retryError: this.promotionFailureCode(error),
+                    });
+                }
+            }
+            if (current()) {
+                const results = binding.registration.listTerminalResults(limit);
+                if (!Array.isArray(results) || results.length > limit) {
+                    throw new PreferenceLearningError('unattested-signal', 'Memory returned an invalid result batch');
+                }
+                for (const raw of results) {
+                    if (!current())
+                        break;
+                    const result = validatePreferenceMemoryPromotionResult(raw);
+                    const acknowledgement = this.store.projectMemoryPromotionResult(result);
+                    binding.registration.acknowledgeTerminalResult(acknowledgement);
+                    projected += 1;
+                }
+            }
+            return Object.freeze({ submitted, cancelled, projected });
+        }
+        finally {
+            this.memoryPromotionReconcileRunning = false;
+        }
+    }
+    promotionFailureCode(error) {
+        const name = error instanceof Error ? error.name : 'unknown-error';
+        return `memory-${name.normalize('NFC').toLowerCase().replaceAll(/[^a-z0-9]+/gu, '-').slice(0, 80)}`;
+    }
+    /** Never call Memory while Delivery is still holding its preference writer lock. */
+    scheduleMemoryPromotionReconcile() {
+        if (this.memoryPromotionBinding === undefined || this.memoryPromotionReconcileScheduled)
+            return;
+        this.memoryPromotionReconcileScheduled = true;
+        queueMicrotask(() => {
+            this.memoryPromotionReconcileScheduled = false;
+            if (!this.active || this.memoryPromotionBinding === undefined)
+                return;
+            try {
+                this.reconcileMemoryPromotions();
+            }
+            catch {
+                this.ctx.logger.warn('preference-learning: Memory promotion reconciliation failed');
+            }
+        });
+    }
     /**
      * Unprivileged observation seam. Actor/source authority is assigned here;
      * callers cannot use it to claim owner feedback or unlock an effect.
@@ -128,23 +359,101 @@ export class PreferenceLearningService extends Service {
     }
     review(agent, limit) {
         this.assertActive();
-        const scope = this.authorizedScope(agent, 'review', 'hypotheses');
-        const hypotheses = this.store.list(scope, limit);
+        const { scope, principalId, principalLineage } = this.authorizedPrincipalScope(agent, 'review', 'hypotheses');
+        const hypotheses = this.store.list(scope, limit, principalId, principalLineage);
         return Object.freeze({
             hypotheses: Object.freeze(hypotheses),
-            activeOverlay: this.config.enabled ? this.store.overlay(scope) : undefined,
+            activeOverlay: this.config.enabled
+                ? this.store.overlaySnapshot(scope, principalId, principalLineage).text
+                : undefined,
+        });
+    }
+    /** Host-only, Agent-free review for the deterministic recovery runbook. */
+    hostReview(input) {
+        this.assertActive();
+        const scope = this.authorizedHostScope(input, 'inspect', 'hypotheses');
+        const principalId = hostText(input.principal, 'principal', 500, 'missing-principal');
+        const fence = this.hostPrincipalFence(input);
+        const hypotheses = this.store.list(scope, input.limit, principalId, {
+            principalRecordId: fence.principalLineageId,
+            principalVersion: fence.principalLineageVersion,
+        });
+        return Object.freeze({
+            hypotheses: Object.freeze(hypotheses),
+            activeOverlay: this.config.enabled
+                ? this.store.overlaySnapshot(scope, principalId, {
+                    principalRecordId: fence.principalLineageId,
+                    principalVersion: fence.principalLineageVersion,
+                }).text
+                : undefined,
+        });
+    }
+    /** Side-effect-free Preference-state fence capture for a fixed Host plan. */
+    hostOwnerFence(input) {
+        this.assertActive();
+        this.authorizedHostScope(input, 'inspect', 'owner-fence');
+        const fence = this.hostPrincipalFence(input);
+        return Object.freeze({
+            ownerGeneration: fence.generation,
+            principalLineage: Object.freeze({
+                principalRecordId: fence.principalLineageId,
+                principalVersion: fence.principalLineageVersion,
+            }),
+        });
+    }
+    /**
+     * Return one deterministic, content-minimal activation target. The Store
+     * evaluates the exact same readiness predicates used by activate().
+     */
+    hostActivationCandidate(input) {
+        this.assertActive();
+        this.assertEnabled();
+        const scope = this.authorizedHostScope(input, 'inspect', 'activation-candidate');
+        const fence = this.hostPrincipalFence(input);
+        const candidate = this.store.activationCandidate(scope, fence);
+        if (candidate === undefined)
+            return undefined;
+        return Object.freeze({
+            hypothesisId: candidate.id,
+            expectedVersion: candidate.version,
+            ownerGeneration: fence.generation,
+            principalLineage: Object.freeze({
+                principalRecordId: fence.principalLineageId,
+                principalVersion: fence.principalLineageVersion,
+            }),
         });
     }
     activate(agent, hypothesisId, expectedVersion) {
         this.assertActive();
         this.assertEnabled();
-        const scope = this.authorizedScope(agent, 'activate', hypothesisId);
-        return this.store.activate(scope, hypothesisId, expectedVersion);
+        const principal = this.authorizedPrincipalScope(agent, 'activate', hypothesisId);
+        return this.store.activate(principal.scope, hypothesisId, expectedVersion, this.requirePrincipalFence(principal));
+    }
+    /** Activate exactly one evidence-ready, owner-attested T1 hypothesis by CAS. */
+    hostActivateOne(input) {
+        this.assertActive();
+        const hypothesisId = hostText(input.hypothesisId, 'hypothesisId', 200);
+        const scope = this.authorizedHostScope(input, 'activate', `hypothesis:${hypothesisId}`);
+        const fence = this.hostPrincipalFence(input);
+        return this.store.activateHostOnce(scope, hypothesisId, input.expectedVersion, input.operationId, fence, this.config.enabled);
     }
     rollback(agent, hypothesisId, expectedVersion, reason) {
         this.assertActive();
-        const scope = this.authorizedScope(agent, 'rollback', hypothesisId);
-        return this.store.rollback(scope, hypothesisId, expectedVersion, reason);
+        const principal = this.authorizedPrincipalScope(agent, 'rollback', hypothesisId);
+        return this.store.rollback(principal.scope, hypothesisId, expectedVersion, reason, this.requirePrincipalFence(principal));
+    }
+    /** Roll back exactly one currently-active T1 overlay by CAS. */
+    hostRollbackOne(input) {
+        this.assertActive();
+        const hypothesisId = hostText(input.hypothesisId, 'hypothesisId', 200);
+        const scope = this.authorizedHostScope(input, 'rollback', `hypothesis:${hypothesisId}`);
+        const principalId = hostText(input.principal, 'principal', 500, 'missing-principal');
+        const fence = this.hostPrincipalFence(input);
+        const current = this.store.get(scope, hypothesisId, principalId, input.principalLineage);
+        if (current?.riskTier !== 'T1' || current.effectState !== 'active') {
+            throw new PreferenceLearningError('unattested-signal', 'Host recovery can only roll back one exact active T1 preference');
+        }
+        return this.store.rollback(scope, hypothesisId, input.expectedVersion, 'regression', fence);
     }
     /** Host-only privacy seam. It removes exact-scope rows and retains only a scope digest tombstone. */
     forgetScope(scope, idempotencyKey) {
@@ -161,6 +470,7 @@ export class PreferenceLearningService extends Service {
             signalTtlMs: this.config.signalTtlMs,
             hypothesisTtlMs: this.config.hypothesisTtlMs,
             minSignalsForActivation: this.config.minSignalsForActivation,
+            minBehavioralSignalsForActivation: this.config.minBehavioralSignalsForActivation,
             minConfidenceBps: this.config.minConfidenceBps,
             maxContradictionBps: this.config.maxContradictionBps,
             maxActiveOverlays: this.config.maxActiveOverlays,
@@ -175,40 +485,411 @@ export class PreferenceLearningService extends Service {
         this.assertActive();
         return this.store.maintain(this.config.maintenanceBatchSize);
     }
+    /** Policy-authorized, exact-scope retention step; deletes at most one row. */
+    hostMaintainOne(input) {
+        this.assertActive();
+        const scope = this.authorizedHostScope(input, 'maintain', 'retention');
+        return this.store.maintainScopeOnce(scope, input.operationId, this.hostPrincipalFence(input));
+    }
     /** Host integration seam for foreground prompt composition. */
     overlayForAgent(agent) {
         this.assertActive();
         if (!this.config.enabled)
             return undefined;
-        const scope = this.authorizedScope(agent, 'snapshot', 'active');
-        return this.store.overlay(scope);
+        const { scope, principalId, principalLineage } = this.authorizedPrincipalScope(agent, 'snapshot', 'active');
+        return this.store.overlaySnapshot(scope, principalId, principalLineage).text;
+    }
+    /** Exact process-local ownership proof; copied or disposed registrations never pass. */
+    ownsDeliveryPreferenceRegistration(registration) {
+        return this.active && typeof registration === 'object' && registration !== null
+            && this.activeDeliveryRegistrations.has(registration);
+    }
+    bindDeliveryProducer(producer) {
+        let generation;
+        try {
+            generation = hostText(producer.trustedPreferenceProducerGeneration(), 'Delivery preference producer generation', 200);
+        }
+        catch {
+            throw new PreferenceLearningError('unattested-signal', 'Delivery preference producer is invalid');
+        }
+        if (this.deliveryBinding?.generation === generation)
+            return this.deliveryBinding.dispose;
+        let live = true;
+        let registration;
+        registration = Object.freeze({
+            protocol: DELIVERY_PREFERENCE_PROJECTION_PROTOCOL,
+            producer: 'preference-learning',
+            generation,
+            owner: this,
+            append: (events) => {
+                if (!live || !this.active || !this.activeDeliveryRegistrations.has(registration)
+                    || producer.trustedPreferenceProducerGeneration() !== generation) {
+                    throw new PreferenceLearningError('unattested-signal', 'stale Delivery preference registration');
+                }
+                return this.appendDeliveryPreferenceBatch(events);
+            },
+            appendSynchronously: (events) => {
+                if (!live || !this.active || !this.activeDeliveryRegistrations.has(registration)
+                    || producer.trustedPreferenceProducerGeneration() !== generation) {
+                    throw new PreferenceLearningError('unattested-signal', 'stale Delivery preference registration');
+                }
+                return this.appendDeliveryPreferenceBatch(events);
+            },
+            control: (request) => {
+                if (!live || !this.active || !this.activeDeliveryRegistrations.has(registration)
+                    || producer.trustedPreferenceProducerGeneration() !== generation) {
+                    throw new PreferenceLearningError('unattested-signal', 'stale Delivery preference registration');
+                }
+                return this.controlDeliveryLearning(request);
+            },
+        });
+        this.activeDeliveryRegistrations.add(registration);
+        let unregister;
+        try {
+            unregister = producer.registerTrustedPreferenceSink(registration);
+            if (typeof unregister !== 'function') {
+                throw new PreferenceLearningError('unattested-signal', 'Delivery preference producer returned no registration disposer');
+            }
+        }
+        catch (error) {
+            live = false;
+            this.activeDeliveryRegistrations.delete(registration);
+            throw error;
+        }
+        let binding;
+        const dispose = () => {
+            if (!live)
+                return;
+            live = false;
+            this.activeDeliveryRegistrations.delete(registration);
+            if (this.deliveryBinding === binding)
+                this.deliveryBinding = undefined;
+            unregister?.();
+        };
+        binding = Object.freeze({ generation, producer, registration, dispose });
+        const previous = this.deliveryBinding;
+        this.deliveryBinding = binding;
+        previous?.dispose();
+        return dispose;
     }
     dynamicOverlay(agent) {
         if (!this.config.enabled || agent === undefined)
             return '';
         try {
-            return this.overlayForAgent(agent) ?? '';
+            const scope = this.authorizedScope(agent, 'snapshot', 'active');
+            const turn = this.deliveryBinding?.producer.currentPreferenceTurn(agent);
+            if (turn === undefined
+                || turn.scope.workspace !== scope.workspace
+                || turn.scope.preset !== scope.preset
+                || turn.sessionId !== String(agent.session.id))
+                return '';
+            const snapshot = this.store.overlaySnapshot(scope, turn.principalId, turn.principalLineage);
+            if (snapshot.ownerFence !== undefined) {
+                for (const hypothesis of snapshot.hypotheses) {
+                    this.store.recordExposure({
+                        scope,
+                        ownerFence: snapshot.ownerFence,
+                        hypothesisId: hypothesis.id,
+                        hypothesisVersion: hypothesis.version,
+                        sessionId: turn.sessionId,
+                        sourceEventId: turn.sourceEventId,
+                    });
+                }
+            }
+            return snapshot.text ?? '';
         }
         catch {
             this.ctx.logger.warn('preference-learning: current scoped overlay is unavailable');
             return '';
         }
     }
+    controlDeliveryLearning(request) {
+        this.assertActive();
+        const principalId = hostText(request.principalId, 'Delivery learning principalId', 500);
+        const idempotencyKey = hostText(request.idempotencyKey, 'Delivery learning idempotencyKey', 500);
+        if (!Number.isSafeInteger(request.occurredAt) || request.occurredAt < 0
+            || !['explain', 'export', 'forget', 'pause', 'resume', 'rollback', 'status'].includes(request.action)
+            || (request.action === 'rollback' ? typeof request.preferenceKey !== 'string'
+                : request.preferenceKey !== undefined)) {
+            throw new PreferenceLearningError('unattested-signal', 'Delivery learning control is invalid');
+        }
+        const admissionCursor = this.deliveryAdmissionCursor(request.admissionCursor);
+        if (admissionCursor === undefined) {
+            return Object.freeze({ outcome: 'stale', action: request.action, idempotencyKey });
+        }
+        const lineage = this.deliveryLineage(request.principalLineage);
+        const principal = this.store.ensureScopePrincipal(request.scope, principalId, request.occurredAt, lineage, admissionCursor);
+        if (!principal.accepted) {
+            return Object.freeze({
+                outcome: 'stale',
+                action: request.action,
+                idempotencyKey,
+            });
+        }
+        try {
+            let replayed = false;
+            let deletedSignals;
+            let deletedHypotheses;
+            let explanation;
+            let exportDocument;
+            let rolledBack;
+            let rolledBackVersion;
+            let state;
+            if (request.action === 'status') {
+                const result = this.store.recordScopeLearningStatus(request.scope, principal, admissionCursor, request.occurredAt, idempotencyKey);
+                if (!result.applied) {
+                    return Object.freeze({ outcome: 'stale', action: request.action, idempotencyKey });
+                }
+                replayed = result.replayed;
+                state = result.state;
+            }
+            else if (request.action === 'explain') {
+                const result = this.store.explainScopeLearning(request.scope, principal, admissionCursor, request.occurredAt, idempotencyKey);
+                if (!result.applied) {
+                    return Object.freeze({ outcome: 'stale', action: request.action, idempotencyKey });
+                }
+                replayed = result.replayed;
+                state = result.state;
+                explanation = result.explanation;
+            }
+            else if (request.action === 'export') {
+                const result = this.store.exportScopeLearning(request.scope, principal, admissionCursor, request.occurredAt, idempotencyKey);
+                if (!result.applied) {
+                    return Object.freeze({ outcome: 'stale', action: request.action, idempotencyKey });
+                }
+                replayed = result.replayed;
+                state = result.state;
+                exportDocument = Object.freeze({
+                    format: 'dsh-preference-learning',
+                    version: 1,
+                    records: result.records,
+                });
+            }
+            else if (request.action === 'pause' || request.action === 'resume') {
+                const result = this.store.setScopeLearningPaused(request.scope, principal, request.action === 'pause', admissionCursor, request.occurredAt, idempotencyKey);
+                if (!result.applied) {
+                    return Object.freeze({ outcome: 'stale', action: request.action, idempotencyKey });
+                }
+                replayed = result.replayed;
+                state = result.state;
+            }
+            else if (request.action === 'rollback') {
+                const result = this.store.rollbackScopeLearningKey(request.scope, principal, request.preferenceKey, admissionCursor, request.occurredAt, idempotencyKey);
+                if (!result.applied) {
+                    return Object.freeze({ outcome: 'stale', action: request.action, idempotencyKey });
+                }
+                replayed = result.replayed;
+                state = result.state;
+                rolledBack = result.rolledBack;
+                rolledBackVersion = result.rolledBackVersion;
+            }
+            else {
+                const forgotten = this.store.forgetScope(request.scope, idempotencyKey, { ownerFence: principal, admissionCursor, occurredAt: request.occurredAt });
+                if (!forgotten.applied) {
+                    return Object.freeze({ outcome: 'stale', action: request.action, idempotencyKey });
+                }
+                replayed = forgotten.replayed;
+                deletedSignals = forgotten.deletedSignals;
+                deletedHypotheses = forgotten.deletedHypotheses;
+                if (forgotten.state === undefined) {
+                    throw new PreferenceLearningError('unattested-signal', 'Delivery forget receipt is missing its exact historical state');
+                }
+                state = forgotten.state;
+            }
+            this.scheduleMemoryPromotionReconcile();
+            return Object.freeze({
+                outcome: 'applied',
+                action: request.action,
+                idempotencyKey,
+                replayed,
+                state: this.deliveryLearningStatus(state),
+                ...(deletedSignals === undefined ? {} : { deletedSignals }),
+                ...(deletedHypotheses === undefined ? {} : { deletedHypotheses }),
+                ...(explanation === undefined ? {} : { explanation }),
+                ...(exportDocument === undefined ? {} : { exportDocument }),
+                ...(rolledBack === undefined ? {} : { rolledBack }),
+                ...(rolledBackVersion === undefined ? {} : { rolledBackVersion }),
+            });
+        }
+        catch (error) {
+            if (error instanceof PreferenceStoreError && error.code === 'conflict') {
+                return Object.freeze({
+                    outcome: 'stale',
+                    action: request.action,
+                    idempotencyKey,
+                });
+            }
+            throw error;
+        }
+    }
+    deliveryLearningStatus(state) {
+        const administrativelyEnabled = this.config.enabled;
+        const effectiveActiveOverlays = administrativelyEnabled && state.mode === 'active'
+            ? state.storedActiveOverlays
+            : 0;
+        return Object.freeze({
+            mode: administrativelyEnabled ? state.mode : 'disabled',
+            administrativelyEnabled,
+            collectionMode: state.mode,
+            signals: state.signals,
+            hypotheses: state.hypotheses,
+            storedActiveOverlays: state.storedActiveOverlays,
+            effectiveActiveOverlays,
+            activeOverlays: effectiveActiveOverlays,
+            shadowHypotheses: state.shadowHypotheses,
+        });
+    }
+    deliveryLineage(input) {
+        if (typeof input !== 'object' || input === null
+            || typeof input.principalRecordId !== 'string'
+            || input.principalRecordId.normalize('NFC').trim() !== input.principalRecordId
+            || input.principalRecordId.length < 1
+            || Buffer.byteLength(input.principalRecordId) > 500
+            || !Number.isSafeInteger(input.principalVersion) || input.principalVersion < 1) {
+            throw new PreferenceLearningError('unattested-signal', 'Delivery owner lineage is invalid');
+        }
+        return Object.freeze({
+            principalRecordId: input.principalRecordId,
+            principalVersion: input.principalVersion,
+        });
+    }
+    deliveryAdmissionCursor(input) {
+        if (input === undefined)
+            return undefined;
+        if (typeof input !== 'object' || input === null
+            || typeof input.epoch !== 'string'
+            || !/^[0-9a-f]{32}$/u.test(input.epoch)
+            || !Number.isSafeInteger(input.sequence) || input.sequence < 1) {
+            throw new PreferenceLearningError('unattested-signal', 'Delivery admission cursor is invalid');
+        }
+        return Object.freeze({ epoch: input.epoch, sequence: input.sequence });
+    }
     /**
      * The closure is registered directly with Assistant Delivery. No public
      * service method accepts owner-authenticated provenance.
      */
-    appendDeliveryFeedbackBatch(events) {
+    appendDeliveryPreferenceBatch(events) {
         this.assertActive();
-        this.assertEnabled();
         if (!Array.isArray(events) || events.length < 1 || events.length > 16) {
             throw new PreferenceLearningError('unattested-signal', 'delivery feedback batch is invalid');
         }
-        const signals = events.map(event => {
-            if (event.stance !== 'support'
-                || event.actorTrust !== 'owner-authenticated'
-                || event.interpretationTrust !== 'typed-feedback'
-                || event.source !== 'direct-owner-feedback') {
+        if (!this.config.enabled) {
+            return Object.freeze(events.map(event => Object.freeze({
+                idempotencyKey: hostText(event.idempotencyKey, 'Delivery preference idempotencyKey', 500),
+                status: 'recorded',
+            })));
+        }
+        const first = events[0];
+        const principalId = hostText(first.principalId, 'Delivery preference principalId', 500);
+        // Projection rows written by a pre-lineage/cursor Delivery build are
+        // terminally ignored. Replaying them into a new owner generation or across
+        // a pause/forget boundary would be unsafe.
+        if (first.principalLineage === undefined
+            || first.admissionCursor === undefined
+            || events.some(event => event.principalLineage === undefined
+                || event.admissionCursor === undefined)) {
+            return Object.freeze(events.map(event => Object.freeze({
+                idempotencyKey: event.idempotencyKey,
+                status: 'recorded',
+            })));
+        }
+        const lineage = this.deliveryLineage(first.principalLineage);
+        const admissionCursor = this.deliveryAdmissionCursor(first.admissionCursor);
+        if (principalId !== first.principalId
+            || events.some(event => event.principalId !== principalId
+                || event.scope.workspace !== first.scope.workspace
+                || event.scope.preset !== first.scope.preset
+                || event.principalLineage?.principalRecordId !== lineage.principalRecordId
+                || event.principalLineage?.principalVersion !== lineage.principalVersion
+                || event.admissionCursor?.epoch !== admissionCursor.epoch
+                || event.admissionCursor?.sequence !== admissionCursor.sequence
+                || !Number.isSafeInteger(event.occurredAt) || event.occurredAt < 0)) {
+            throw new PreferenceLearningError('unattested-signal', 'delivery preference owner fence is invalid');
+        }
+        const principal = this.store.ensureScopePrincipal(first.scope, principalId, first.occurredAt, lineage, admissionCursor);
+        if (!principal.accepted) {
+            return Object.freeze(events.map(event => Object.freeze({
+                idempotencyKey: event.idempotencyKey,
+                status: 'recorded',
+            })));
+        }
+        const admittedEvents = events.filter(event => this.store.scopeAcceptsEvent(event.scope, principal, admissionCursor));
+        if (admittedEvents.length === 0) {
+            return Object.freeze(events.map(event => Object.freeze({
+                idempotencyKey: event.idempotencyKey,
+                status: 'recorded',
+            })));
+        }
+        try {
+            for (const event of admittedEvents) {
+                if (event.source === 'direct-owner-feedback')
+                    continue;
+                const completion = this.deliveryCompletion(event);
+                this.store.bindExposure({
+                    admissionCursor,
+                    scope: event.scope,
+                    ownerFence: principal,
+                    sessionId: completion.sessionId,
+                    sourceEventId: completion.sourceEventId,
+                    sourceInboxId: completion.sourceInboxId,
+                    replyOutboxId: completion.replyOutboxId,
+                });
+            }
+            const signalEvents = admittedEvents.filter((event) => event.source !== 'delivery-completion');
+            const signals = signalEvents.map(event => this.deliverySignal(event));
+            if (signals.length > 0) {
+                this.store.appendSignals(signals, {
+                    admissionCursor,
+                    ownerFence: principal,
+                    exactCorrections: signalEvents.flatMap((event, signalIndex) => event.source === 'direct-owner-feedback' && event.exposureTarget !== undefined
+                        ? [Object.freeze({
+                                signalIndex,
+                                sourceInboxId: event.exposureTarget.sourceInboxId,
+                                replyOutboxId: event.exposureTarget.sourceOutboxId,
+                            })]
+                        : []),
+                });
+                this.store.enqueueEligibleMemoryPromotions(first.scope, principalId, principal);
+            }
+            if (this.config.autonomousT1Enabled) {
+                const scopes = new Map(admittedEvents.map(event => [
+                    JSON.stringify([event.scope.workspace, event.scope.preset]),
+                    { workspace: event.scope.workspace, preset: event.scope.preset },
+                ]));
+                for (const scope of scopes.values()) {
+                    this.store.activateReady(scope, this.config.maxActiveOverlays, principal);
+                }
+            }
+        }
+        catch (error) {
+            if (!(error instanceof PreferenceStoreError && error.code === 'learning-paused'))
+                throw error;
+        }
+        this.scheduleMemoryPromotionReconcile();
+        return Object.freeze(events.map(event => Object.freeze({
+            idempotencyKey: event.idempotencyKey,
+            status: 'recorded',
+        })));
+    }
+    deliveryCompletion(event) {
+        const completion = event.completion;
+        if (event.actorTrust !== 'owner-authenticated'
+            || typeof completion !== 'object' || completion === null
+            || !Number.isSafeInteger(completion.bindingVersion) || completion.bindingVersion < 1
+            || [completion.bindingId, completion.sessionId, completion.sourceEventId,
+                completion.sourceInboxId, completion.replyOutboxId]
+                .some(value => typeof value !== 'string' || value.length < 1 || Buffer.byteLength(value) > 500)) {
+            throw new PreferenceLearningError('unattested-signal', 'delivery completion attestation is invalid');
+        }
+        return completion;
+    }
+    deliverySignal(event) {
+        if (event.stance !== 'support' || event.actorTrust !== 'owner-authenticated') {
+            throw new PreferenceLearningError('unattested-signal', 'delivery preference attestation is invalid');
+        }
+        if (event.source === 'direct-owner-feedback') {
+            if (event.interpretationTrust !== 'explicit-selection'
+                && event.interpretationTrust !== 'typed-feedback') {
                 throw new PreferenceLearningError('unattested-signal', 'delivery feedback attestation is invalid');
             }
             return {
@@ -217,17 +898,31 @@ export class PreferenceLearningService extends Service {
                 candidateValue: event.candidateValue,
                 stance: 'support',
                 actorTrust: 'owner-authenticated',
-                interpretationTrust: 'typed-feedback',
+                interpretationTrust: event.interpretationTrust,
                 source: 'direct-owner-feedback',
                 occurredAt: event.occurredAt,
                 idempotencyKey: `assistant-delivery:${event.idempotencyKey}`,
             };
-        });
-        this.store.appendSignals(signals);
-        return Object.freeze(events.map(event => Object.freeze({
-            idempotencyKey: event.idempotencyKey,
-            status: 'recorded',
-        })));
+        }
+        const observation = event;
+        this.deliveryCompletion(observation);
+        if (observation.source !== 'delivery-observation'
+            || observation.interpretationTrust !== 'behavioral-inference'
+            || observation.preferenceKey !== 'response.language'
+            || (observation.candidateValue !== 'zh-CN' && observation.candidateValue !== 'en')) {
+            throw new PreferenceLearningError('unattested-signal', 'delivery observation attestation is invalid');
+        }
+        return {
+            scope: { workspace: observation.scope.workspace, preset: observation.scope.preset },
+            preferenceKey: 'response.language',
+            candidateValue: observation.candidateValue,
+            stance: 'support',
+            actorTrust: 'owner-authenticated',
+            interpretationTrust: 'behavioral-inference',
+            source: 'delivery-observation',
+            occurredAt: observation.occurredAt,
+            idempotencyKey: `assistant-delivery:${observation.idempotencyKey}`,
+        };
     }
     authorizedScope(agent, action, resourceId) {
         const header = agent?.session?.header;
@@ -247,6 +942,76 @@ export class PreferenceLearningService extends Service {
             throw decisionError(decision);
         return scope;
     }
+    authorizedPrincipalScope(agent, action, resourceId) {
+        const scope = this.authorizedScope(agent, action, resourceId);
+        const principal = agent === undefined
+            ? undefined
+            : this.deliveryBinding?.producer.preferencePrincipalForAgent(agent);
+        if (principal === undefined
+            || principal.scope.workspace !== scope.workspace
+            || principal.scope.preset !== scope.preset
+            || principal.sessionId !== String(agent.session.id)) {
+            throw new PreferenceLearningError('missing-agent', `missing-agent: preference ${action} requires an exact owner Delivery binding`);
+        }
+        return Object.freeze({
+            scope,
+            principalId: hostText(principal.principalId, 'Delivery preference principalId', 500),
+            principalLineage: this.deliveryLineage(principal.principalLineage),
+        });
+    }
+    requirePrincipalFence(input) {
+        const fence = this.store.scopePrincipalFence(input.scope, input.principalId, input.principalLineage);
+        if (fence === undefined) {
+            throw new PreferenceLearningError('missing-principal', 'Delivery owner lineage is not current for this preference scope');
+        }
+        return fence;
+    }
+    authorizedHostScope(input, action, resourceId) {
+        const scope = exactHostScope(input.scope);
+        const principal = hostText(input.principal, 'principal', 500, 'missing-principal');
+        const principalLineage = this.deliveryLineage(input.principalLineage);
+        if (input.ownerGeneration !== undefined
+            && (!Number.isSafeInteger(input.ownerGeneration) || input.ownerGeneration < 1)) {
+            throw new PreferenceLearningError('invalid-input', 'ownerGeneration is invalid');
+        }
+        const operationId = hostText(input.operationId, 'operationId', 500);
+        const idempotencyDigest = createHash('sha256').update(JSON.stringify([
+            HOST_RECOVERY_BACKGROUND_ID,
+            scope.workspace,
+            scope.preset,
+            principal,
+            principalLineage.principalRecordId,
+            principalLineage.principalVersion,
+            input.ownerGeneration ?? 'current',
+            action,
+            resourceId,
+            operationId,
+        ])).digest('hex');
+        const decision = this.policy.authorize({
+            subject: {
+                kind: 'background',
+                id: HOST_RECOVERY_BACKGROUND_ID,
+                workspace: scope.workspace,
+                principal,
+            },
+            action,
+            resource: { kind: 'preference', id: resourceId },
+            context: { initiator: 'background' },
+        }, { idempotencyKey: `preference-host:${idempotencyDigest}` });
+        if (decision.effect !== 'allow')
+            throw decisionError(decision);
+        return scope;
+    }
+    hostPrincipalFence(input) {
+        const scope = exactHostScope(input.scope);
+        const principal = hostText(input.principal, 'principal', 500, 'missing-principal');
+        const lineage = this.deliveryLineage(input.principalLineage);
+        const fence = this.store.scopePrincipalFence(scope, principal, lineage, input.ownerGeneration);
+        if (fence === undefined) {
+            throw new PreferenceLearningError('missing-principal', 'Host preference owner lineage is stale or unavailable');
+        }
+        return fence;
+    }
     assertEnabled() {
         if (!this.config.enabled)
             throw new PreferenceLearningError('disabled', 'preference learning is disabled');