@bizagent/dsh 0.0.0-stage → 1.0.0

package/lib/domain.js

@@ -0,0 +1,662 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+export const HOME_TYPES = ['personal', 'line', 'business', 'role', 'capability'];
+export const ORGANIZATION_RELATIONS = ['member-of', 'fulfills-role', 'serves', 'belongs-to-line'];
+export const ASSET_KINDS = ['memory', 'insight', 'knowledge', 'method', 'identity'];
+export const ASSET_STATUSES = ['candidate', 'active', 'superseded', 'retired'];
+export const HomeAddressSchema = z.string().refine((value) => {
+    const separator = value.indexOf(':');
+    if (separator <= 0 || separator === value.length - 1)
+        return false;
+    return HOME_TYPES.includes(value.slice(0, separator))
+        && /^[a-z0-9][a-z0-9._/-]*$/i.test(value.slice(separator + 1));
+}, 'expected <personal|line|business|role|capability>:<id>');
+export const UserAddressSchema = z.string().regex(/^user:[a-z0-9][a-z0-9._-]{0,127}$/i);
+export const ProjectSeatAddressSchema = z.string().regex(/^seat:[a-z0-9][a-z0-9._-]{0,127}:seat-[a-f0-9]{20}$/);
+export const InboxAddressSchema = z.union([HomeAddressSchema, UserAddressSchema, ProjectSeatAddressSchema]);
+export const InboxSenderAddressSchema = z.union([InboxAddressSchema, z.literal('engine:inbox')]);
+export const HumanActionSchema = z.strictObject({
+    request: z.string().trim().min(1).max(3000),
+    reason: z.string().trim().min(1).max(3000),
+    recommendation: z.string().trim().min(1).max(3000).optional(),
+    href: z.string().max(2000).optional(),
+    label: z.string().trim().min(1).max(80).optional(),
+}).superRefine((action, context) => {
+    if (action.href === undefined)
+        return;
+    try {
+        const decoded = decodeURIComponent(action.href);
+        if (!decoded.startsWith('/') || decoded.startsWith('//') || /[\\\s\u0000-\u001f]/u.test(decoded)) {
+            throw new Error('unsafe path');
+        }
+        const url = new URL(action.href, 'https://bizagent.invalid');
+        if (url.origin !== 'https://bizagent.invalid' || url.pathname.startsWith('/api/')) {
+            throw new Error('unsafe path');
+        }
+    }
+    catch {
+        context.addIssue({ code: 'custom', path: ['href'], message: 'human action href must be an application page path' });
+    }
+});
+export const EvidenceRefSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('session-events'),
+        sessionId: z.string().min(1),
+        fromSeq: z.number().int().nonnegative(),
+        toSeq: z.number().int().nonnegative(),
+    }),
+    z.object({
+        type: z.literal('worklog'),
+        sessionId: z.string().min(1),
+        revisionId: z.string().min(1),
+        fingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+    }),
+    z.object({
+        type: z.literal('tool-result'),
+        sessionId: z.string().min(1),
+        eventSeq: z.number().int().nonnegative(),
+        toolCallId: z.string().min(1),
+    }),
+    z.object({
+        type: z.literal('artifact'),
+        uri: z.string().min(1),
+        digest: z.string().min(1),
+    }),
+    z.object({
+        type: z.literal('document'),
+        uri: z.string().min(1),
+        digest: z.string().min(1),
+        authority: z.string().min(1).optional(),
+    }),
+    z.object({
+        type: z.literal('asset'),
+        ownerAddress: HomeAddressSchema,
+        assetId: z.string().min(1),
+        revision: z.number().int().positive(),
+    }),
+    z.object({
+        type: z.literal('user-confirmation'),
+        sessionId: z.string().min(1),
+        eventSeq: z.number().int().nonnegative(),
+    }),
+]);
+export const AgentHomeSchema = z.object({
+    schemaVersion: z.literal(1),
+    id: z.string().min(1),
+    address: HomeAddressSchema,
+    type: z.enum(HOME_TYPES),
+    displayName: z.string().min(1),
+    owner: z.string().min(1).optional(),
+    revision: z.number().int().positive(),
+    contextDigest: z.string(),
+    status: z.enum(['active', 'archived']),
+    createdAt: z.string().min(1),
+    updatedAt: z.string().min(1),
+});
+export const OrganizationLinkSchema = z.object({
+    from: HomeAddressSchema,
+    to: HomeAddressSchema,
+    relation: z.enum(ORGANIZATION_RELATIONS),
+});
+export const OrganizationSchema = z.object({
+    schemaVersion: z.literal(1),
+    id: z.string().regex(/^[a-z0-9][a-z0-9._-]{0,63}$/),
+    name: z.string().min(1),
+    mission: z.string().min(1),
+    lineHome: HomeAddressSchema.optional(),
+    businessHome: HomeAddressSchema,
+    members: z.array(z.object({
+        personalHome: HomeAddressSchema,
+        roleHome: HomeAddressSchema,
+    })).min(1),
+    capabilityHomes: z.array(HomeAddressSchema),
+    links: z.array(OrganizationLinkSchema),
+    revision: z.number().int().positive(),
+    createdAt: z.string().min(1),
+    updatedAt: z.string().min(1),
+}).superRefine((organization, context) => {
+    if (!organization.businessHome.startsWith('business:')) {
+        context.addIssue({ code: 'custom', path: ['businessHome'], message: 'businessHome must be a Business Home' });
+    }
+    if (organization.lineHome !== undefined && !organization.lineHome.startsWith('line:')) {
+        context.addIssue({ code: 'custom', path: ['lineHome'], message: 'lineHome must be a Line Home' });
+    }
+    const declared = new Set([organization.businessHome,
+        ...(organization.lineHome === undefined ? [] : [organization.lineHome])]);
+    const seenMembers = new Set();
+    organization.members.forEach((member, index) => {
+        if (!member.personalHome.startsWith('personal:')) {
+            context.addIssue({ code: 'custom', path: ['members', index, 'personalHome'], message: 'member must use a Personal Home' });
+        }
+        if (!member.roleHome.startsWith('role:')) {
+            context.addIssue({ code: 'custom', path: ['members', index, 'roleHome'], message: 'member role must use a Role Home' });
+        }
+        if (seenMembers.has(member.personalHome)) {
+            context.addIssue({ code: 'custom', path: ['members', index, 'personalHome'], message: 'duplicate organization member' });
+        }
+        seenMembers.add(member.personalHome);
+        declared.add(member.personalHome);
+        declared.add(member.roleHome);
+    });
+    organization.capabilityHomes.forEach((address, index) => {
+        if (!address.startsWith('capability:')) {
+            context.addIssue({ code: 'custom', path: ['capabilityHomes', index], message: 'capability must use a Capability Home' });
+        }
+        declared.add(address);
+    });
+    organization.links.forEach((link, index) => {
+        if (!declared.has(link.from) || !declared.has(link.to)) {
+            context.addIssue({ code: 'custom', path: ['links', index], message: 'link endpoints must belong to this organization' });
+        }
+        const validShape = link.relation === 'member-of'
+            ? link.from.startsWith('personal:') && link.to === organization.businessHome
+            : link.relation === 'fulfills-role'
+                ? link.from.startsWith('personal:') && link.to.startsWith('role:')
+                : link.relation === 'belongs-to-line'
+                    ? organization.lineHome !== undefined && link.to === organization.lineHome
+                        && (link.from.startsWith('business:') || link.from.startsWith('role:')
+                            || link.from.startsWith('capability:'))
+                    : (link.from.startsWith('role:') || link.from.startsWith('capability:'))
+                        && link.to === organization.businessHome;
+        if (!validShape)
+            context.addIssue({ code: 'custom', path: ['links', index], message: 'relation has invalid Home types' });
+    });
+});
+export const AssetMetadataSchema = z.object({
+    schemaVersion: z.literal(1),
+    id: z.string().min(1),
+    ownerAddress: HomeAddressSchema,
+    kind: z.enum(ASSET_KINDS),
+    title: z.string().min(1).optional(),
+    description: z.string().min(1).max(1000),
+    tags: z.array(z.string().min(1).max(80)).default([]),
+    sourceRefs: z.array(EvidenceRefSchema).min(1),
+    confidence: z.number().min(0).max(1),
+    fitness: z.number().min(-1).max(1),
+    status: z.enum(ASSET_STATUSES),
+    revision: z.number().int().positive(),
+    proposalId: z.string().min(1).optional(),
+    proposalApplications: z.array(z.object({
+        proposalId: z.string().min(1), revision: z.number().int().positive(),
+        bodySha256: z.string().regex(/^[a-f0-9]{64}$/),
+    })).max(500).optional(),
+    createdAt: z.string().min(1),
+    updatedAt: z.string().min(1),
+}).superRefine((asset, context) => {
+    const applications = asset.proposalApplications ?? [];
+    if (new Set(applications.map(item => item.proposalId)).size !== applications.length
+        || applications.some(item => item.revision > asset.revision)) {
+        context.addIssue({ code: 'custom', message: 'asset proposal applications conflict with revision history' });
+    }
+});
+export const SessionBindingSchema = z.object({
+    sessionId: z.string().min(1),
+    homeAddress: HomeAddressSchema,
+    cwd: z.string().optional(),
+    boundAt: z.string().min(1),
+});
+export const ProjectTurnParticipationSchema = z.object({
+    schemaVersion: z.literal(1),
+    projectId: z.string().min(1).max(128),
+    sessionId: z.string().min(1),
+    homeAddress: HomeAddressSchema,
+    turn: z.number().int().nonnegative(),
+    recordedAt: z.string().datetime(),
+});
+export const LearningMaterialObservationSchema = z.object({
+    schemaVersion: z.literal(1),
+    id: z.string().min(1),
+    homeAddress: HomeAddressSchema,
+    sessionId: z.string().min(1),
+    fingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+    eventCount: z.number().int().positive(),
+    lastSeq: z.number().int().nonnegative(),
+    sourceKind: z.literal('worklog').optional(),
+    worklogRevisionId: z.string().min(1).optional(),
+    worklogRevision: z.number().int().positive().optional(),
+    observedAt: z.string().min(1),
+}).superRefine((observation, context) => {
+    if (observation.sourceKind === 'worklog'
+        ? observation.worklogRevisionId === undefined || observation.worklogRevision === undefined
+        : observation.worklogRevisionId !== undefined || observation.worklogRevision !== undefined) {
+        context.addIssue({ code: 'custom', path: ['worklogRevisionId'],
+            message: 'Worklog material requires an exact revision ID and number' });
+    }
+});
+export const LearningMaterialReviewSchema = z.object({
+    schemaVersion: z.literal(1),
+    materialId: z.string().min(1),
+    homeAddress: HomeAddressSchema,
+    reviewerSessionId: z.string().min(1),
+    summary: z.string().min(1).max(2000),
+    batchRunId: z.string().min(1).optional(),
+    assetIds: z.array(z.string().min(1)).max(3).optional(),
+    reviewedAt: z.string().min(1),
+});
+export const LearningLibraryFileSchema = z.object({
+    path: z.string().min(1).max(500),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    bytes: z.number().int().nonnegative().max(8 * 1024 * 1024),
+});
+export const LearningLibraryChangeSchema = z.object({
+    path: z.string().min(1).max(500),
+    result: z.enum(['created', 'updated', 'deleted']),
+    before: LearningLibraryFileSchema.optional(),
+    after: LearningLibraryFileSchema.optional(),
+}).superRefine((change, context) => {
+    if (change.before?.path !== undefined && change.before.path !== change.path
+        || change.after?.path !== undefined && change.after.path !== change.path
+        || change.result === 'created' && (change.before !== undefined || change.after === undefined)
+        || change.result === 'deleted' && (change.before === undefined || change.after !== undefined)
+        || change.result === 'updated' && (change.before === undefined || change.after === undefined
+            || change.before.sha256 === change.after.sha256)) {
+        context.addIssue({ code: 'custom', path: ['result'], message: 'invalid learning library change' });
+    }
+});
+export const LearningBatchRunSchema = z.object({
+    schemaVersion: z.literal(1),
+    id: z.string().min(1),
+    homeAddress: HomeAddressSchema,
+    reviewerSessionId: z.string().min(1),
+    materialIds: z.array(z.string().min(1)).min(1).max(8),
+    status: z.enum(['open', 'completed', 'abandoned']),
+    summary: z.string().min(1).max(2000).optional(),
+    libraryBefore: z.array(LearningLibraryFileSchema).max(1000).optional(),
+    libraryChanges: z.array(LearningLibraryChangeSchema).max(1000).optional(),
+    libraryChangeError: z.string().min(1).max(500).optional(),
+    createdAt: z.string().min(1),
+    updatedAt: z.string().min(1),
+}).superRefine((run, context) => {
+    if (new Set(run.materialIds).size !== run.materialIds.length) {
+        context.addIssue({ code: 'custom', path: ['materialIds'], message: 'duplicate learning material' });
+    }
+    if (run.status !== 'open' && run.summary === undefined) {
+        context.addIssue({ code: 'custom', path: ['summary'], message: 'settled learning batch requires a summary' });
+    }
+    if (new Set((run.libraryBefore ?? []).map(file => file.path)).size !== (run.libraryBefore?.length ?? 0)
+        || new Set((run.libraryChanges ?? []).map(change => change.path)).size !== (run.libraryChanges?.length ?? 0)
+        || (run.status === 'open' && run.libraryChanges !== undefined)
+        || (run.status === 'open' && run.libraryChangeError !== undefined)
+        || (run.libraryChangeError !== undefined && run.libraryBefore === undefined)
+        || (run.libraryChanges !== undefined && (run.libraryBefore === undefined
+            || run.libraryChangeError !== undefined))) {
+        context.addIssue({ code: 'custom', path: ['libraryChanges'], message: 'invalid learning library snapshot chain' });
+    }
+});
+export const LearningLaunchSchema = z.object({
+    schemaVersion: z.literal(1),
+    id: z.string().min(1),
+    homeAddress: HomeAddressSchema,
+    requestedBySessionId: z.string().min(1),
+    workerSessionId: z.string().min(1),
+    workspace: z.string().min(1),
+    promptMessageId: z.string().min(1),
+    provider: z.string().min(1).max(200).optional(),
+    model: z.string().min(1).max(200).optional(),
+    maxTokens: z.number().int().positive().optional(),
+    trigger: z.enum(['explicit', 'schedule']).optional(),
+    scheduledFor: z.number().int().nonnegative().optional(),
+    status: z.enum(['reserved', 'active', 'completed', 'needs_review', 'abandoned']),
+    reason: z.string().min(1).max(2000).optional(),
+    createdAt: z.string().min(1),
+    updatedAt: z.string().min(1),
+}).superRefine((launch, context) => {
+    if (launch.trigger === 'schedule' && launch.scheduledFor === undefined) {
+        context.addIssue({ code: 'custom', path: ['scheduledFor'], message: 'scheduled learning launch needs its due time' });
+    }
+    if (launch.status === 'needs_review' && !launch.reason) {
+        context.addIssue({ code: 'custom', path: ['reason'], message: 'uncertain learning launch needs a reason' });
+    }
+});
+export const LearningScheduleCursorSchema = z.object({
+    schemaVersion: z.literal(1),
+    homeAddress: HomeAddressSchema,
+    scheduleFingerprint: z.string().min(1),
+    nextDueAt: z.number().int().nonnegative(),
+    lastDueAt: z.number().int().nonnegative().optional(),
+    lastOutcome: z.enum(['launched', 'empty', 'limit', 'deferred', 'expired']).optional(),
+    lastLaunchId: z.string().min(1).optional(),
+    lastReason: z.string().min(1).max(2000).optional(),
+    updatedAt: z.string().min(1),
+});
+export const LearningSchedulePolicySchema = z.object({
+    schemaVersion: z.literal(1),
+    homeAddress: HomeAddressSchema,
+    revision: z.number().int().positive(),
+    enabled: z.boolean(),
+    cron: z.string().min(1).max(100),
+    dailyRuns: z.number().int().min(1).max(4),
+    updatedBy: z.literal('local-ui'),
+    updatedAt: z.string().min(1),
+});
+export const FRAME_MODES = ['lead', 'contribute', 'reference'];
+export const AgentFrameSchema = z.object({
+    address: HomeAddressSchema,
+    mode: z.enum(FRAME_MODES),
+    revision: z.number().int().positive(),
+    digest: z.string(),
+    contextEpoch: z.number().int().positive().optional(),
+    openedAt: z.string().min(1),
+    updatedAt: z.string().min(1),
+});
+export const AgentFrameStateSchema = z.object({
+    schemaVersion: z.literal(1),
+    sessionId: z.string().min(1),
+    primaryHome: HomeAddressSchema,
+    contextEpoch: z.number().int().positive().optional(),
+    lastCompactionSeq: z.number().int().nonnegative().optional(),
+    frames: z.array(AgentFrameSchema).max(8),
+    focusAddress: HomeAddressSchema.optional(),
+    updatedAt: z.string().min(1),
+}).superRefine((state, context) => {
+    const addresses = new Set();
+    let leads = 0;
+    state.frames.forEach((frame, index) => {
+        if (frame.address === state.primaryHome || addresses.has(frame.address)) {
+            context.addIssue({ code: 'custom', path: ['frames', index, 'address'], message: 'frame address must be unique and different from the primary Home' });
+        }
+        addresses.add(frame.address);
+        if (frame.mode === 'lead')
+            leads += 1;
+    });
+    if (leads > 1)
+        context.addIssue({ code: 'custom', path: ['frames'], message: 'only one lead Frame is allowed' });
+    if (state.focusAddress !== undefined && !addresses.has(state.focusAddress)) {
+        context.addIssue({ code: 'custom', path: ['focusAddress'], message: 'focus must name an active Frame' });
+    }
+});
+export const HumanTurnProvenanceSchema = z.strictObject({
+    sessionId: z.string().min(1),
+    turn: z.number().int().nonnegative(),
+    fromSeq: z.number().int().nonnegative(),
+    userMessageSeq: z.number().int().nonnegative(),
+    toSeq: z.number().int().nonnegative(),
+    sourceSha256: z.string().regex(/^[a-f0-9]{64}$/),
+    recipient: UserAddressSchema,
+    authorityRef: z.string().min(1).max(500),
+    summary: z.string().trim().min(1).max(160).regex(/^[^\r\n\u0000-\u001f]+$/u).optional(),
+}).refine(value => value.fromSeq < value.userMessageSeq && value.userMessageSeq < value.toSeq, 'human turn source sequence is invalid');
+export const InboxMessageSchema = z.object({
+    schemaVersion: z.literal(1),
+    id: z.string().min(1),
+    idempotencyKey: z.string().min(1).max(128),
+    fromAddress: InboxSenderAddressSchema,
+    returnToSessionId: z.string().min(1).optional(),
+    /** Frozen from the sender so an automatic wake can run after host recovery. */
+    wakeOptions: z.object({
+        provider: z.string().min(1).optional(),
+        model: z.string().min(1).optional(),
+        maxTokens: z.number().int().positive().optional(),
+    }).optional(),
+    returnAddress: z.union([HomeAddressSchema, ProjectSeatAddressSchema]).optional(),
+    projectId: z.string().min(1).max(128).optional(),
+    to: z.array(InboxAddressSchema).min(1).max(8),
+    cc: z.array(InboxAddressSchema).max(8),
+    subject: z.string().min(1).max(200),
+    body: z.string().min(1).max(16000),
+    kind: z.enum(['ordinary', 'project-outcome-rework', 'conclusion', 'escalation', 'work-request', 'work-result', 'work-notice',
+        'turn-complete']),
+    priority: z.enum(['normal', 'urgent']),
+    due: z.string().min(1).optional(),
+    contextRefs: z.array(z.string().min(1).max(500)).max(16),
+    humanAction: HumanActionSchema.optional(),
+    humanTurn: HumanTurnProvenanceSchema.optional(),
+    projectOutcomeRework: z.strictObject({
+        projectId: z.string().min(1), claimId: z.string().min(1), lead: HomeAddressSchema,
+    }).optional(),
+    automaticEscalation: z.object({
+        sourceMessageId: z.string().min(1),
+        authorityRef: z.string().min(1).max(500),
+    }).optional(),
+    conclusionArtifact: z.string().min(1).max(500).optional(),
+    replyTo: z.string().min(1).optional(),
+    rootId: z.string().min(1),
+    chain: z.number().int().min(0).max(7),
+    topicId: z.string().min(1).optional(),
+    hop: z.number().int().min(0).max(7).optional(),
+    sentAt: z.string().min(1),
+}).superRefine((message, context) => {
+    const seats = [message.fromAddress, ...message.to, ...message.cc, message.returnAddress]
+        .filter((address) => address !== undefined && isProjectSeatAddress(address));
+    if (seats.some(address => message.projectId === undefined
+        || !address.startsWith(`seat:${message.projectId}:`))) {
+        context.addIssue({ code: 'custom', path: ['projectId'], message: 'Inbox Seat addresses must belong to the recorded Project' });
+    }
+    if (message.humanTurn && (message.kind !== 'turn-complete'
+        || message.to.length !== 1 || message.to[0] !== message.humanTurn.recipient
+        || message.cc.length !== 0 || !message.humanAction?.href
+        || message.priority !== 'normal' || message.contextRefs.length !== 0
+        || message.due !== undefined || message.replyTo !== undefined
+        || message.returnToSessionId !== message.humanTurn.sessionId
+        || message.returnAddress !== message.fromAddress)) {
+        context.addIssue({ code: 'custom', path: ['humanTurn'],
+            message: 'human turn completion needs one recipient and its source Session' });
+    }
+    if (message.kind === 'turn-complete' && !message.humanTurn) {
+        context.addIssue({ code: 'custom', path: ['humanTurn'],
+            message: 'turn completion needs durable Session provenance' });
+    }
+    if (message.projectOutcomeRework && (message.kind !== 'project-outcome-rework'
+        || message.fromAddress !== 'engine:inbox'
+        || message.projectId !== message.projectOutcomeRework.projectId
+        || message.id !== stableId('project-outcome-rework', `${message.projectOutcomeRework.projectId}:${message.projectOutcomeRework.claimId}`)
+        || message.to.length !== 1 || message.to[0] !== message.projectOutcomeRework.lead
+        || message.cc.length !== 0 || message.priority !== 'urgent')) {
+        context.addIssue({ code: 'custom', path: ['projectOutcomeRework'],
+            message: 'Project outcome rework notice must target its lead Home with stable provenance' });
+    }
+    if (message.kind === 'project-outcome-rework' && !message.projectOutcomeRework) {
+        context.addIssue({ code: 'custom', path: ['projectOutcomeRework'],
+            message: 'Project outcome rework notice needs durable Project provenance' });
+    }
+});
+export function inboxShouldConverge(hop, topicCount) {
+    return hop >= 4 || topicCount >= 9;
+}
+export const InboxWakeOriginSchema = z.object({
+    schemaVersion: z.literal(1),
+    sessionId: z.string().min(1),
+    homeAddress: HomeAddressSchema,
+    topicId: z.string().min(1),
+    hop: z.number().int().min(0).max(6),
+    wakePlanId: z.string().min(1),
+    createdAt: z.string().min(1),
+});
+export const InboxWakePlanSchema = z.object({
+    schemaVersion: z.literal(1),
+    id: z.string().min(1),
+    recipient: z.union([HomeAddressSchema, ProjectSeatAddressSchema]),
+    messageIds: z.array(z.string().min(1)).min(1).max(20),
+    sessionId: z.string().min(1),
+    topicId: z.string().min(1),
+    scope: z.enum(['topic', 'owner']).optional(),
+    reason: z.enum(['initial', 'nudge-due', 'nudge-stale']).optional(),
+    hop: z.number().int().min(0).max(6),
+    workspace: z.string().min(1),
+    dueAt: z.string().min(1),
+    createdAt: z.string().min(1),
+    dispatchedAt: z.string().min(1).optional(),
+    /** Why the plan was retired without starting a Session; its letters stay in the normal Inbox. */
+    retiredReason: z.string().min(1).max(500).optional(),
+});
+export const InboxReturnRouteSchema = z.object({
+    schemaVersion: z.literal(1),
+    messageId: z.string().min(1),
+    recipient: z.union([HomeAddressSchema, ProjectSeatAddressSchema]),
+    sessionId: z.string().min(1),
+    status: z.enum(['queued', 'fallback']),
+    updatedAt: z.string().min(1),
+    reason: z.string().min(1).optional(),
+});
+export const InboxDeliverySchema = z.object({
+    schemaVersion: z.literal(1),
+    messageId: z.string().min(1),
+    recipient: InboxAddressSchema,
+    status: z.enum(['delivered', 'bounced']),
+    reason: z.string().min(1).optional(),
+    wakePolicy: z.enum(['immediate', 'batch', 'scheduled', 'carried']).optional(),
+    wakeAt: z.string().min(1).optional(),
+    nudgedAt: z.string().min(1).optional(),
+    nudgeReason: z.enum(['due', 'stale']).optional(),
+    handledAt: z.string().min(1).optional(),
+    handledBySessionId: z.string().min(1).optional(),
+    handledByUserId: z.string().min(1).optional(),
+    updatedAt: z.string().min(1),
+});
+export const HumanNotificationPreferenceSchema = z.strictObject({
+    schemaVersion: z.literal(1), recipient: UserAddressSchema,
+    enabled: z.boolean(), revision: z.number().int().positive(),
+    updatedAt: z.string().datetime(),
+});
+/** A push attempt is unknown before calling an external channel, so crashes cannot cause blind resend. */
+export const InboxHumanNotificationSchema = z.object({
+    schemaVersion: z.literal(1),
+    id: z.string().min(1),
+    messageId: z.string().min(1),
+    recipient: UserAddressSchema,
+    attempt: z.number().int().nonnegative().default(1),
+    priorRejections: z.array(z.object({
+        id: z.string().min(1),
+        attemptedAt: z.string().min(1),
+        resolvedAt: z.string().min(1),
+        reason: z.string().min(1),
+    })).default([]),
+    status: z.enum(['unknown', 'sent', 'rejected', 'suppressed']),
+    attemptedAt: z.string().min(1).optional(),
+    suppressedAt: z.string().datetime().optional(),
+    resolvedAt: z.string().min(1).optional(),
+    providerReceipt: z.string().min(1).optional(),
+    reason: z.string().min(1).optional(),
+}).superRefine((notice, context) => {
+    if (notice.status === 'suppressed') {
+        if (notice.attempt !== 0 || notice.attemptedAt || !notice.suppressedAt
+            || notice.resolvedAt !== notice.suppressedAt || !notice.reason?.trim()
+            || notice.providerReceipt || notice.priorRejections.length > 0) {
+            context.addIssue({ code: 'custom', message: 'suppressed notice cannot have an external attempt' });
+        }
+        return;
+    }
+    if (notice.attempt < 1 || !notice.attemptedAt || notice.suppressedAt) {
+        context.addIssue({ code: 'custom', message: 'channel notice needs an actual attempt' });
+    }
+    if (notice.status === 'sent' && !notice.providerReceipt) {
+        context.addIssue({ code: 'custom', path: ['providerReceipt'], message: 'sent requires a provider receipt' });
+    }
+    if (notice.status === 'rejected' && !notice.reason) {
+        context.addIssue({ code: 'custom', path: ['reason'], message: 'rejected requires a reason' });
+    }
+});
+export const MemoryProposalSchema = z.object({
+    id: z.string().min(1),
+    fromAddress: HomeAddressSchema,
+    toAddress: HomeAddressSchema,
+    proposedKind: z.enum(ASSET_KINDS),
+    description: z.string().min(1).max(1000),
+    body: z.string().min(1),
+    tags: z.array(z.string().min(1).max(80)).default([]),
+    sourceRefs: z.array(EvidenceRefSchema).min(1),
+    status: z.enum(['pending', 'accepted', 'rejected', 'withdrawn']),
+    baseAsset: z.object({ id: z.string().min(1), revision: z.number().int().positive(),
+        bodySha256: z.string().regex(/^[a-f0-9]{64}$/) }).optional(),
+    targetAssetId: z.string().min(1).optional(),
+    appliedAssetRevision: z.number().int().positive().optional(),
+    appliedBodySha256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    humanReview: z.object({
+        reviewerId: z.string().trim().min(1),
+        authorityRef: z.string().trim().min(1),
+        action: z.enum(['accept', 'reject']),
+        decision: z.string().trim().min(1),
+        reviewedAt: z.string().min(1),
+    }).optional(),
+    decision: z.string().min(1).optional(),
+    createdAt: z.string().min(1),
+    decidedAt: z.string().min(1).optional(),
+}).superRefine((proposal, context) => {
+    if ((proposal.appliedAssetRevision === undefined) !== (proposal.appliedBodySha256 === undefined)) {
+        context.addIssue({ code: 'custom', message: 'proposal application revision and digest must appear together' });
+    }
+    if (proposal.baseAsset && proposal.status === 'accepted'
+        && (proposal.targetAssetId !== proposal.baseAsset.id || proposal.appliedAssetRevision === undefined)) {
+        context.addIssue({ code: 'custom', message: 'accepted replacement proposal needs a matching applied asset' });
+    }
+    if (proposal.humanReview && proposal.status === 'pending' && proposal.humanReview.action !== 'accept') {
+        context.addIssue({ code: 'custom', message: 'pending proposal can only reserve human acceptance' });
+    }
+    if (proposal.humanReview && proposal.status !== 'pending'
+        && ((proposal.status === 'accepted' ? 'accept' : 'reject') !== proposal.humanReview.action
+            || proposal.decision !== proposal.humanReview.decision
+            || proposal.decidedAt !== proposal.humanReview.reviewedAt)) {
+        context.addIssue({ code: 'custom', message: 'proposal decision must match its human review' });
+    }
+});
+export const FITNESS_SIGNALS = ['retrieved', 'applied', 'confirmed', 'contradicted', 'failed'];
+export const FitnessReceiptSchema = z.object({
+    id: z.string().min(1),
+    assetId: z.string().min(1),
+    ownerAddress: HomeAddressSchema,
+    sessionId: z.string().min(1),
+    eventSeq: z.number().int().nonnegative().optional(),
+    assetRevision: z.number().int().positive().optional(),
+    assetBodySha256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    signal: z.enum(FITNESS_SIGNALS),
+    outcome: z.string().min(1).optional(),
+    createdAt: z.string().min(1),
+}).superRefine((receipt, context) => {
+    if ((receipt.assetRevision === undefined) !== (receipt.assetBodySha256 === undefined)) {
+        context.addIssue({ code: 'custom', path: ['assetBodySha256'],
+            message: 'fitness receipt asset version and body digest must appear together' });
+    }
+});
+export const LEARNING_CHECKPOINT_STATUSES = ['pending', 'remembered', 'skipped', 'failed'];
+export const LearningCheckpointSchema = z.object({
+    schemaVersion: z.literal(1),
+    id: z.string().min(1),
+    sessionId: z.string().min(1),
+    turn: z.number().int().nonnegative(),
+    homeAddress: HomeAddressSchema,
+    reason: z.literal('explicit-correction'),
+    status: z.enum(LEARNING_CHECKPOINT_STATUSES),
+    evidenceRef: EvidenceRefSchema,
+    excerpt: z.string().min(1).max(4000),
+    assetId: z.string().min(1).optional(),
+    decision: z.string().min(1).optional(),
+    createdAt: z.string().min(1),
+    settledAt: z.string().min(1).optional(),
+});
+export function parseHomeAddress(value) {
+    return HomeAddressSchema.parse(value);
+}
+export function parseInboxAddress(value) {
+    return InboxAddressSchema.parse(value);
+}
+export function isUserAddress(value) {
+    return UserAddressSchema.safeParse(value).success;
+}
+export function isHomeAddress(value) {
+    return HomeAddressSchema.safeParse(value).success;
+}
+export function isProjectSeatAddress(value) {
+    return ProjectSeatAddressSchema.safeParse(value).success;
+}
+export function parseUserAddress(value) {
+    return UserAddressSchema.parse(value);
+}
+export function homeTypeOf(address) {
+    return address.slice(0, address.indexOf(':'));
+}
+export function stableId(prefix, value) {
+    return `${prefix}-${createHash('sha256').update(value).digest('hex').slice(0, 20)}`;
+}
+export function safeHomeId(address) {
+    const readable = address
+        .toLowerCase()
+        .replace(':', '--')
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 64);
+    return `${readable}-${createHash('sha256').update(address).digest('hex').slice(0, 8)}`;
+}
+export function nowIso() {
+    return new Date().toISOString();
+}
+//# sourceMappingURL=domain.js.map

package/lib/frame-admission.d.ts

@@ -0,0 +1,6 @@
+import type { Agent, PreStepDecision } from '@deepseek-ai/dsh-agent';
+import type { BizAgentService } from './service.js';
+import './message-source.js';
+/** Resolve selected references at DSH's admission boundary, before the model sees the step. */
+export declare function admitFrameReferences(service: BizAgentService, agent: Agent, decision: PreStepDecision, signal: AbortSignal): Promise<PreStepDecision>;
+//# sourceMappingURL=frame-admission.d.ts.map