agl 1.0.17 → 21.0.2

package/ts/classes.flexmodels.private.ts

@@ -0,0 +1,823 @@
+import * as plugins from './plugins.js';
+import {
+  type IFlexModelChoice,
+  type IFlexPublicAccountSummary,
+  hasFlexExactKeys,
+  isFlexPlainObject,
+  isFlexPublicProviderConnection,
+} from './interfaces.flexipc.js';
+import {
+  type IFlexProjectionSourceManifest,
+  isFlexProjectionSourceManifest,
+} from './classes.flexmodels.public.js';
+
+export const flexPrivateChunkBytes = 384 * 1024;
+
+export type TFlexDomainKind =
+  | 'scope'
+  | 'projection'
+  | 'permission'
+  | 'agentEvents'
+  | 'agentArchive'
+  | 'jobs';
+
+export interface IFlexPrivateChunkManifest {
+  id: string;
+  index: number;
+  sha256: string;
+  bytes: number;
+}
+
+export interface IFlexPrivateCandidateManifest {
+  candidateId: string;
+  revision: number;
+  sha256: string;
+  bytes: number;
+  chunks: IFlexPrivateChunkManifest[];
+}
+
+export interface IFlexPrivateChunkDocument extends IFlexPrivateChunkManifest {
+  controllerId: string;
+  scopeId: string;
+  candidateId: string;
+  revision: number;
+  data: string;
+  createdAt: string;
+  domain?: TFlexDomainKind;
+  incarnationId?: string;
+  sessionId?: string;
+  archiveId?: string;
+}
+
+export interface IFlexPrivateCandidateDocument extends IFlexPrivateCandidateManifest {
+  id: string;
+  controllerId: string;
+  scopeId: string;
+  createdAt: string;
+  domain?: TFlexDomainKind;
+  incarnationId?: string;
+  sessionId?: string;
+  archiveId?: string;
+}
+
+export interface IFlexDomainHeadDocument {
+  id: string;
+  controllerId: string;
+  storageKey: string;
+  domain: TFlexDomainKind;
+  incarnationId: string;
+  revision: number;
+  currentPrivateCandidateId: string;
+  privateCandidate: IFlexPrivateCandidateManifest;
+  projectionSource?: IFlexProjectionSourceManifest;
+  sessionId?: string;
+  archiveId?: string;
+}
+
+export interface IFlexWriterLeaseDocument {
+  id: string;
+  controllerId: string;
+  storageKey: string;
+  ownerToken: string;
+  epoch: number;
+  state: 'active' | 'released';
+  expiresAt: number;
+  updatedAt: string;
+}
+
+export interface IFlexMigrationDocument {
+  id: string;
+  controllerId: string;
+  storageKey: string;
+  migration: 'flexharness-v3';
+  legacyRevision: number;
+  legacyCandidateId: string;
+  completedAt: string;
+}
+
+export interface IFlexLegacyPublicCandidateManifest {
+  candidateId: string;
+  revision: number;
+  sha256: string;
+  bytes: number;
+  sessionRecords: Array<{ id: string; sha256: string; bytes: number }>;
+  messageRecords: Array<{ id: string; sha256: string; bytes: number }>;
+  sessionsTruncated: boolean;
+  messagesTruncated: boolean;
+  messageBytesTruncated: boolean;
+}
+
+export interface IFlexHeadDocument {
+  id: string;
+  controllerId: string;
+  storageKey: string;
+  revision: number;
+  currentPrivateCandidateId: string;
+  currentPublicCandidateId: string;
+  privateCandidates: IFlexPrivateCandidateManifest[];
+  publicCandidates: IFlexLegacyPublicCandidateManifest[];
+}
+
+export interface IFlexProviderConnectionDocument {
+  id: string;
+  controllerId: string;
+  providerId: 'openai';
+  state: 'pending' | 'active' | 'deleting' | 'reauthRequired';
+  generation: number;
+  createdAt: string;
+  updatedAt: string;
+  account?: IFlexPublicAccountSummary;
+}
+
+export interface IFlexModelChoiceDocument {
+  id: string;
+  controllerId: string;
+  projectId: string;
+  generation: number;
+  choice: IFlexModelChoice;
+  updatedAt: string;
+}
+
+const digestPattern = /^[a-f0-9]{64}$/u;
+const candidateIdPattern = /^[A-Za-z0-9_-]{22}$/u;
+const ownerTokenPattern = /^[A-Za-z0-9_-]{43}$/u;
+const qualifiedConnectionIdPattern = /^flex:provider:openai:[A-Za-z0-9_-]{22}$/u;
+
+const isBoundedString = (valueArg: unknown, maximumBytesArg: number): valueArg is string =>
+  typeof valueArg === 'string'
+  && valueArg.length > 0
+  && Buffer.byteLength(valueArg, 'utf8') <= maximumBytesArg;
+
+const isNonNegativeInteger = (valueArg: unknown): valueArg is number =>
+  Number.isSafeInteger(valueArg) && (valueArg as number) >= 0;
+
+const isIsoDate = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string'
+  && Number.isFinite(Date.parse(valueArg))
+  && new Date(valueArg).toISOString() === valueArg;
+
+const hasValidOptionalDomainIdentity = (valueArg: Record<string, unknown>): boolean => {
+  if (valueArg.domain === undefined) {
+    return valueArg.incarnationId === undefined
+      && valueArg.sessionId === undefined
+      && valueArg.archiveId === undefined;
+  }
+  const sessionDomain = valueArg.domain === 'projection'
+    || valueArg.domain === 'permission'
+    || valueArg.domain === 'agentEvents'
+    || valueArg.domain === 'agentArchive'
+    || valueArg.domain === 'jobs';
+  const archiveDomain = valueArg.domain === 'agentArchive';
+  return ['scope', 'projection', 'permission', 'agentEvents', 'agentArchive', 'jobs']
+    .includes(String(valueArg.domain))
+    && typeof valueArg.incarnationId === 'string'
+    && candidateIdPattern.test(valueArg.incarnationId)
+    && (sessionDomain
+      ? isBoundedString(valueArg.sessionId, 512)
+      : valueArg.sessionId === undefined)
+    && (archiveDomain
+      ? isBoundedString(valueArg.archiveId, 512)
+      : valueArg.archiveId === undefined);
+};
+
+export const isFlexPrivateChunkManifest = (
+  valueArg: unknown,
+): valueArg is IFlexPrivateChunkManifest => isFlexPlainObject(valueArg)
+  && hasFlexExactKeys(valueArg, ['id', 'index', 'sha256', 'bytes'])
+  && isBoundedString(valueArg.id, 1024)
+  && isNonNegativeInteger(valueArg.index)
+  && typeof valueArg.sha256 === 'string'
+  && digestPattern.test(valueArg.sha256)
+  && isNonNegativeInteger(valueArg.bytes)
+  && valueArg.bytes <= flexPrivateChunkBytes;
+
+export const isFlexPrivateCandidateManifest = (
+  valueArg: unknown,
+): valueArg is IFlexPrivateCandidateManifest => isFlexPlainObject(valueArg)
+  && hasFlexExactKeys(valueArg, ['candidateId', 'revision', 'sha256', 'bytes', 'chunks'])
+  && typeof valueArg.candidateId === 'string'
+  && candidateIdPattern.test(valueArg.candidateId)
+  && isNonNegativeInteger(valueArg.revision)
+  && typeof valueArg.sha256 === 'string'
+  && digestPattern.test(valueArg.sha256)
+  && isNonNegativeInteger(valueArg.bytes)
+  && Array.isArray(valueArg.chunks)
+  && valueArg.chunks.length >= 1
+  && valueArg.chunks.every(isFlexPrivateChunkManifest)
+  && valueArg.chunks.every((chunk, index) => chunk.index === index)
+  && valueArg.chunks.reduce((total, chunk) => total + chunk.bytes, 0) === valueArg.bytes;
+
+const isFlexLegacyRecordManifest = (valueArg: unknown): boolean => isFlexPlainObject(valueArg)
+  && hasFlexExactKeys(valueArg, ['id', 'sha256', 'bytes'])
+  && isBoundedString(valueArg.id, 1024)
+  && typeof valueArg.sha256 === 'string'
+  && digestPattern.test(valueArg.sha256)
+  && isNonNegativeInteger(valueArg.bytes);
+
+const isFlexLegacyPublicCandidateManifest = (
+  valueArg: unknown,
+): valueArg is IFlexLegacyPublicCandidateManifest => isFlexPlainObject(valueArg)
+  && hasFlexExactKeys(valueArg, [
+    'candidateId', 'revision', 'sha256', 'bytes',
+    'sessionRecords', 'messageRecords', 'sessionsTruncated',
+    'messagesTruncated', 'messageBytesTruncated',
+  ])
+  && typeof valueArg.candidateId === 'string'
+  && candidateIdPattern.test(valueArg.candidateId)
+  && isNonNegativeInteger(valueArg.revision)
+  && typeof valueArg.sha256 === 'string'
+  && digestPattern.test(valueArg.sha256)
+  && isNonNegativeInteger(valueArg.bytes)
+  && Array.isArray(valueArg.sessionRecords)
+  && valueArg.sessionRecords.every(isFlexLegacyRecordManifest)
+  && Array.isArray(valueArg.messageRecords)
+  && valueArg.messageRecords.every(isFlexLegacyRecordManifest)
+  && typeof valueArg.sessionsTruncated === 'boolean'
+  && typeof valueArg.messagesTruncated === 'boolean'
+  && typeof valueArg.messageBytesTruncated === 'boolean';
+
+export function assertFlexPrivateChunkDocument(
+  valueArg: unknown,
+): asserts valueArg is IFlexPrivateChunkDocument {
+  if (
+    !isFlexPlainObject(valueArg)
+    || !hasFlexExactKeys(valueArg, [
+      'id', 'controllerId', 'scopeId', 'candidateId', 'revision',
+      'index', 'sha256', 'bytes', 'data', 'createdAt',
+    ], ['domain', 'incarnationId', 'sessionId', 'archiveId'])
+    || !isBoundedString(valueArg.controllerId, 512)
+    || !isBoundedString(valueArg.scopeId, 512)
+    || typeof valueArg.candidateId !== 'string'
+    || !candidateIdPattern.test(valueArg.candidateId)
+    || !isNonNegativeInteger(valueArg.revision)
+    || !isIsoDate(valueArg.createdAt)
+    || !isFlexPrivateChunkManifest({
+      id: valueArg.id,
+      index: valueArg.index,
+      sha256: valueArg.sha256,
+      bytes: valueArg.bytes,
+    })
+    || !isBoundedString(valueArg.data, Math.ceil(flexPrivateChunkBytes / 3) * 4 + 4)
+    || !hasValidOptionalDomainIdentity(valueArg)
+  ) throw new Error('Invalid Flex private chunk document.');
+}
+
+export function assertFlexPrivateCandidateDocument(
+  valueArg: unknown,
+): asserts valueArg is IFlexPrivateCandidateDocument {
+  if (
+    !isFlexPlainObject(valueArg)
+    || !hasFlexExactKeys(valueArg, [
+      'id', 'controllerId', 'scopeId', 'candidateId', 'revision',
+      'sha256', 'bytes', 'chunks', 'createdAt',
+    ], ['domain', 'incarnationId', 'sessionId', 'archiveId'])
+    || !isBoundedString(valueArg.id, 1024)
+    || !isBoundedString(valueArg.controllerId, 512)
+    || !isBoundedString(valueArg.scopeId, 512)
+    || !isIsoDate(valueArg.createdAt)
+    || !isFlexPrivateCandidateManifest({
+      candidateId: valueArg.candidateId,
+      revision: valueArg.revision,
+      sha256: valueArg.sha256,
+      bytes: valueArg.bytes,
+      chunks: valueArg.chunks,
+    })
+    || !hasValidOptionalDomainIdentity(valueArg)
+  ) throw new Error('Invalid Flex private candidate document.');
+}
+
+export function assertFlexHeadDocument(
+  valueArg: unknown,
+): asserts valueArg is IFlexHeadDocument {
+  if (
+    !isFlexPlainObject(valueArg)
+    || !hasFlexExactKeys(valueArg, [
+      'id', 'controllerId', 'storageKey', 'revision',
+      'currentPrivateCandidateId', 'currentPublicCandidateId',
+      'privateCandidates', 'publicCandidates',
+    ])
+    || !isBoundedString(valueArg.id, 1024)
+    || !isBoundedString(valueArg.controllerId, 512)
+    || !isBoundedString(valueArg.storageKey, 512)
+    || !isNonNegativeInteger(valueArg.revision)
+    || typeof valueArg.currentPrivateCandidateId !== 'string'
+    || !candidateIdPattern.test(valueArg.currentPrivateCandidateId)
+    || typeof valueArg.currentPublicCandidateId !== 'string'
+    || !candidateIdPattern.test(valueArg.currentPublicCandidateId)
+    || !Array.isArray(valueArg.privateCandidates)
+    || valueArg.privateCandidates.length !== 1
+    || !valueArg.privateCandidates.every(isFlexPrivateCandidateManifest)
+    || !Array.isArray(valueArg.publicCandidates)
+    || valueArg.publicCandidates.length < 1
+    || valueArg.publicCandidates.length > 4
+    || !valueArg.publicCandidates.every(isFlexLegacyPublicCandidateManifest)
+    || valueArg.privateCandidates[0]?.candidateId !== valueArg.currentPrivateCandidateId
+    || valueArg.publicCandidates[0]?.candidateId !== valueArg.currentPublicCandidateId
+    || valueArg.privateCandidates[0]?.revision !== valueArg.revision
+    || valueArg.publicCandidates[0]?.revision !== valueArg.revision
+    || valueArg.publicCandidates.some((candidate, index, candidates) => (
+      index > 0 && candidate.revision >= candidates[index - 1]!.revision
+    ))
+  ) throw new Error('Invalid Flex head document.');
+}
+
+export function assertFlexDomainHeadDocument(
+  valueArg: unknown,
+): asserts valueArg is IFlexDomainHeadDocument {
+  if (!isFlexPlainObject(valueArg)) throw new Error('Invalid Flex domain head document.');
+  const domain = valueArg.domain;
+  const sessionDomain = domain === 'projection'
+    || domain === 'permission'
+    || domain === 'agentEvents'
+    || domain === 'agentArchive'
+    || domain === 'jobs';
+  const archiveDomain = domain === 'agentArchive';
+  if (
+    !hasFlexExactKeys(valueArg, [
+      'id', 'controllerId', 'storageKey', 'domain', 'incarnationId', 'revision',
+      'currentPrivateCandidateId', 'privateCandidate',
+    ], ['projectionSource', 'sessionId', 'archiveId'])
+    || !isBoundedString(valueArg.id, 1024)
+    || !isBoundedString(valueArg.controllerId, 512)
+    || !isBoundedString(valueArg.storageKey, 512)
+    || !['scope', 'projection', 'permission', 'agentEvents', 'agentArchive', 'jobs']
+      .includes(String(domain))
+    || typeof valueArg.incarnationId !== 'string'
+    || !candidateIdPattern.test(valueArg.incarnationId)
+    || !isNonNegativeInteger(valueArg.revision)
+    || valueArg.revision < 1
+    || typeof valueArg.currentPrivateCandidateId !== 'string'
+    || !candidateIdPattern.test(valueArg.currentPrivateCandidateId)
+    || !isFlexPrivateCandidateManifest(valueArg.privateCandidate)
+    || valueArg.privateCandidate.candidateId !== valueArg.currentPrivateCandidateId
+    || valueArg.privateCandidate.revision !== valueArg.revision
+    || (domain === 'projection'
+      ? !isFlexProjectionSourceManifest(valueArg.projectionSource)
+      : valueArg.projectionSource !== undefined)
+    || (sessionDomain
+      ? !isBoundedString(valueArg.sessionId, 512)
+      : valueArg.sessionId !== undefined)
+    || (archiveDomain
+      ? !isBoundedString(valueArg.archiveId, 512)
+      : valueArg.archiveId !== undefined)
+  ) throw new Error('Invalid Flex domain head document.');
+}
+
+export function assertFlexWriterLeaseDocument(
+  valueArg: unknown,
+): asserts valueArg is IFlexWriterLeaseDocument {
+  if (
+    !isFlexPlainObject(valueArg)
+    || !hasFlexExactKeys(valueArg, [
+      'id', 'controllerId', 'storageKey', 'ownerToken', 'epoch',
+      'state', 'expiresAt', 'updatedAt',
+    ])
+    || !isBoundedString(valueArg.id, 1024)
+    || !isBoundedString(valueArg.controllerId, 512)
+    || !isBoundedString(valueArg.storageKey, 512)
+    || typeof valueArg.ownerToken !== 'string'
+    || !ownerTokenPattern.test(valueArg.ownerToken)
+    || !isNonNegativeInteger(valueArg.epoch)
+    || valueArg.epoch < 1
+    || (valueArg.state !== 'active' && valueArg.state !== 'released')
+    || !isNonNegativeInteger(valueArg.expiresAt)
+    || valueArg.expiresAt < 0
+    || !isIsoDate(valueArg.updatedAt)
+  ) throw new Error('Invalid Flex writer lease document.');
+}
+
+export function assertFlexMigrationDocument(
+  valueArg: unknown,
+): asserts valueArg is IFlexMigrationDocument {
+  if (
+    !isFlexPlainObject(valueArg)
+    || !hasFlexExactKeys(valueArg, [
+      'id', 'controllerId', 'storageKey', 'migration',
+      'legacyRevision', 'legacyCandidateId', 'completedAt',
+    ])
+    || !isBoundedString(valueArg.id, 1024)
+    || !isBoundedString(valueArg.controllerId, 512)
+    || !isBoundedString(valueArg.storageKey, 512)
+    || valueArg.migration !== 'flexharness-v3'
+    || !isNonNegativeInteger(valueArg.legacyRevision)
+    || typeof valueArg.legacyCandidateId !== 'string'
+    || !candidateIdPattern.test(valueArg.legacyCandidateId)
+    || !isIsoDate(valueArg.completedAt)
+  ) throw new Error('Invalid Flex migration document.');
+}
+
+export function assertFlexProviderConnectionDocument(
+  valueArg: unknown,
+): asserts valueArg is IFlexProviderConnectionDocument {
+  if (
+    !isFlexPlainObject(valueArg)
+    || !hasFlexExactKeys(valueArg, [
+      'id', 'controllerId', 'providerId', 'state', 'generation', 'createdAt', 'updatedAt',
+    ], ['account'])
+    || typeof valueArg.id !== 'string'
+    || !qualifiedConnectionIdPattern.test(valueArg.id)
+    || !isBoundedString(valueArg.controllerId, 512)
+    || valueArg.providerId !== 'openai'
+    || !['pending', 'active', 'deleting', 'reauthRequired'].includes(String(valueArg.state))
+    || !isNonNegativeInteger(valueArg.generation)
+    || !isIsoDate(valueArg.createdAt)
+    || !isIsoDate(valueArg.updatedAt)
+    || (valueArg.account !== undefined && !isFlexPublicProviderConnection({
+      loginId: valueArg.id,
+      providerId: valueArg.providerId,
+      status: valueArg.state,
+      account: valueArg.account,
+    }))
+  ) throw new Error('Invalid Flex provider connection document.');
+}
+
+export function assertFlexModelChoiceDocument(
+  valueArg: unknown,
+): asserts valueArg is IFlexModelChoiceDocument {
+  if (
+    !isFlexPlainObject(valueArg)
+    || !hasFlexExactKeys(valueArg, [
+      'id', 'controllerId', 'projectId', 'generation', 'choice', 'updatedAt',
+    ])
+    || !isBoundedString(valueArg.id, 1024)
+    || !isBoundedString(valueArg.controllerId, 512)
+    || !isBoundedString(valueArg.projectId, 128)
+    || !isNonNegativeInteger(valueArg.generation)
+    || !isIsoDate(valueArg.updatedAt)
+    || !isFlexPlainObject(valueArg.choice)
+    || !hasFlexExactKeys(valueArg.choice, ['providerConnectionId', 'modelId'], ['variant'])
+    || typeof valueArg.choice.providerConnectionId !== 'string'
+    || !qualifiedConnectionIdPattern.test(valueArg.choice.providerConnectionId)
+    || !isBoundedString(valueArg.choice.modelId, 256)
+    || (valueArg.choice.variant !== undefined && !isBoundedString(valueArg.choice.variant, 128))
+  ) throw new Error('Invalid Flex model choice document.');
+}
+
+@plugins.smartdata.managed({ collectionName: 'flex_private_chunks' })
+export class FlexPrivateChunkModel extends plugins.smartdata.SmartDataDbDoc<
+  FlexPrivateChunkModel,
+  IFlexPrivateChunkDocument
+> {
+  @plugins.smartdata.unI()
+  public id!: string;
+
+  @plugins.smartdata.svDb()
+  public controllerId!: string;
+
+  @plugins.smartdata.index()
+  public scopeId!: string;
+
+  @plugins.smartdata.index()
+  public candidateId!: string;
+
+  @plugins.smartdata.svDb()
+  public revision!: number;
+
+  @plugins.smartdata.svDb()
+  public index!: number;
+
+  @plugins.smartdata.svDb()
+  public sha256!: string;
+
+  @plugins.smartdata.svDb()
+  public bytes!: number;
+
+  @plugins.smartdata.svDb()
+  public data!: string;
+
+  @plugins.smartdata.index()
+  public createdAt!: string;
+
+  @plugins.smartdata.index()
+  public domain?: TFlexDomainKind;
+
+  @plugins.smartdata.svDb()
+  public incarnationId?: string;
+
+  @plugins.smartdata.index()
+  public sessionId?: string;
+
+  @plugins.smartdata.index()
+  public archiveId?: string;
+}
+
+@plugins.smartdata.compoundIndex({
+  name: 'flex_private_candidate_orphans',
+  key: { controllerId: 1, createdAt: 1, _id: 1 },
+})
+@plugins.smartdata.managed({ collectionName: 'flex_private_candidates' })
+export class FlexPrivateCandidateModel extends plugins.smartdata.SmartDataDbDoc<
+  FlexPrivateCandidateModel,
+  IFlexPrivateCandidateDocument
+> {
+  @plugins.smartdata.unI()
+  public id!: string;
+
+  @plugins.smartdata.svDb()
+  public controllerId!: string;
+
+  @plugins.smartdata.index()
+  public scopeId!: string;
+
+  @plugins.smartdata.index()
+  public candidateId!: string;
+
+  @plugins.smartdata.svDb()
+  public revision!: number;
+
+  @plugins.smartdata.svDb()
+  public sha256!: string;
+
+  @plugins.smartdata.svDb()
+  public bytes!: number;
+
+  @plugins.smartdata.svDb()
+  public chunks!: IFlexPrivateChunkManifest[];
+
+  @plugins.smartdata.index()
+  public createdAt!: string;
+
+  @plugins.smartdata.index()
+  public domain?: TFlexDomainKind;
+
+  @plugins.smartdata.svDb()
+  public incarnationId?: string;
+
+  @plugins.smartdata.index()
+  public sessionId?: string;
+
+  @plugins.smartdata.index()
+  public archiveId?: string;
+}
+
+@plugins.smartdata.compoundIndex({
+  name: 'flex_head_public_owner',
+  key: { controllerId: 1, 'publicCandidates.candidateId': 1 },
+})
+@plugins.smartdata.compoundIndex({
+  name: 'flex_head_private_owner',
+  key: { controllerId: 1, currentPrivateCandidateId: 1 },
+})
+@plugins.smartdata.managed({ collectionName: 'flex_heads' })
+@plugins.smartdata.exactPersistence({ assertDocument: assertFlexHeadDocument })
+export class FlexHeadModel extends plugins.smartdata.SmartDataDbDoc<
+  FlexHeadModel,
+  IFlexHeadDocument
+> {
+  declare static exact: plugins.smartdata.TExact<FlexHeadModel>;
+
+  @plugins.smartdata.unI()
+  public id!: string;
+
+  @plugins.smartdata.svDb()
+  public controllerId!: string;
+
+  @plugins.smartdata.svDb()
+  public storageKey!: string;
+
+  @plugins.smartdata.svDb()
+  public revision!: number;
+
+  @plugins.smartdata.svDb()
+  public currentPrivateCandidateId!: string;
+
+  @plugins.smartdata.svDb()
+  public currentPublicCandidateId!: string;
+
+  @plugins.smartdata.svDb()
+  public privateCandidates!: IFlexPrivateCandidateManifest[];
+
+  @plugins.smartdata.svDb()
+  public publicCandidates!: IFlexLegacyPublicCandidateManifest[];
+}
+
+@plugins.smartdata.compoundIndex({
+  name: 'flex_domain_projection_source_owner',
+  key: { controllerId: 1, domain: 1, 'projectionSource.candidateId': 1 },
+})
+@plugins.smartdata.compoundIndex({
+  name: 'flex_domain_private_owner',
+  key: { controllerId: 1, currentPrivateCandidateId: 1 },
+})
+@plugins.smartdata.managed({ collectionName: 'flex_domain_heads' })
+@plugins.smartdata.exactPersistence({ assertDocument: assertFlexDomainHeadDocument })
+export class FlexDomainHeadModel extends plugins.smartdata.SmartDataDbDoc<
+  FlexDomainHeadModel,
+  IFlexDomainHeadDocument
+> {
+  declare static exact: plugins.smartdata.TExact<FlexDomainHeadModel>;
+
+  @plugins.smartdata.unI()
+  public id!: string;
+
+  @plugins.smartdata.index()
+  public controllerId!: string;
+
+  @plugins.smartdata.index()
+  public storageKey!: string;
+
+  @plugins.smartdata.index()
+  public domain!: TFlexDomainKind;
+
+  @plugins.smartdata.svDb()
+  public incarnationId!: string;
+
+  @plugins.smartdata.svDb()
+  public revision!: number;
+
+  @plugins.smartdata.svDb()
+  public currentPrivateCandidateId!: string;
+
+  @plugins.smartdata.svDb()
+  public privateCandidate!: IFlexPrivateCandidateManifest;
+
+  @plugins.smartdata.svDb()
+  public projectionSource?: IFlexProjectionSourceManifest;
+
+  @plugins.smartdata.index()
+  public sessionId?: string;
+
+  @plugins.smartdata.index()
+  public archiveId?: string;
+}
+
+@plugins.smartdata.compoundIndex({
+  name: 'flex_writer_released_scan',
+  key: { controllerId: 1, state: 1, _id: 1 },
+})
+@plugins.smartdata.managed({ collectionName: 'flex_writer_leases' })
+@plugins.smartdata.exactPersistence({ assertDocument: assertFlexWriterLeaseDocument })
+export class FlexWriterLeaseModel extends plugins.smartdata.SmartDataDbDoc<
+  FlexWriterLeaseModel,
+  IFlexWriterLeaseDocument
+> {
+  declare static exact: plugins.smartdata.TExact<FlexWriterLeaseModel>;
+
+  @plugins.smartdata.unI()
+  public id!: string;
+
+  @plugins.smartdata.index()
+  public controllerId!: string;
+
+  @plugins.smartdata.index()
+  public storageKey!: string;
+
+  @plugins.smartdata.svDb()
+  public ownerToken!: string;
+
+  @plugins.smartdata.svDb()
+  public epoch!: number;
+
+  @plugins.smartdata.index()
+  public state!: 'active' | 'released';
+
+  @plugins.smartdata.index()
+  public expiresAt!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: string;
+}
+
+@plugins.smartdata.managed({ collectionName: 'flex_migrations' })
+@plugins.smartdata.exactPersistence({ assertDocument: assertFlexMigrationDocument })
+export class FlexMigrationModel extends plugins.smartdata.SmartDataDbDoc<
+  FlexMigrationModel,
+  IFlexMigrationDocument
+> {
+  declare static exact: plugins.smartdata.TExact<FlexMigrationModel>;
+
+  @plugins.smartdata.unI()
+  public id!: string;
+
+  @plugins.smartdata.index()
+  public controllerId!: string;
+
+  @plugins.smartdata.index()
+  public storageKey!: string;
+
+  @plugins.smartdata.index()
+  public migration!: 'flexharness-v3';
+
+  @plugins.smartdata.svDb()
+  public legacyRevision!: number;
+
+  @plugins.smartdata.svDb()
+  public legacyCandidateId!: string;
+
+  @plugins.smartdata.svDb()
+  public completedAt!: string;
+}
+
+const scopedIdentityHash = (
+  controllerIdArg: string,
+  storageKeyArg: string,
+  ...partsArg: string[]
+): string => plugins.crypto.createHash('sha256')
+  .update(controllerIdArg, 'utf8')
+  .update('\0', 'utf8')
+  .update(storageKeyArg, 'utf8')
+  .update('\0', 'utf8')
+  .update(partsArg.join('\0'), 'utf8')
+  .digest('hex');
+
+export const flexDomainHeadId = (
+  controllerIdArg: string,
+  storageKeyArg: string,
+  domainArg: TFlexDomainKind,
+  sessionIdArg?: string,
+  archiveIdArg?: string,
+): string => `flex-domain-head:${scopedIdentityHash(
+  controllerIdArg,
+  storageKeyArg,
+  domainArg,
+  sessionIdArg ?? '',
+  archiveIdArg ?? '',
+)}`;
+
+export const flexWriterLeaseId = (
+  controllerIdArg: string,
+  storageKeyArg: string,
+): string => `flex-writer-lease:${scopedIdentityHash(controllerIdArg, storageKeyArg, 'writer')}`;
+
+export const flexMigrationId = (
+  controllerIdArg: string,
+  storageKeyArg: string,
+): string => `flex-migration:${scopedIdentityHash(controllerIdArg, storageKeyArg, 'flexharness-v3')}`;
+
+@plugins.smartdata.managed({ collectionName: 'flex_provider_connections' })
+export class FlexProviderConnectionModel extends plugins.smartdata.SmartDataDbDoc<
+  FlexProviderConnectionModel,
+  IFlexProviderConnectionDocument
+> {
+  @plugins.smartdata.unI()
+  public id!: string;
+
+  @plugins.smartdata.index()
+  public controllerId!: string;
+
+  @plugins.smartdata.svDb()
+  public providerId!: 'openai';
+
+  @plugins.smartdata.index()
+  public state!: IFlexProviderConnectionDocument['state'];
+
+  @plugins.smartdata.svDb()
+  public generation!: number;
+
+  @plugins.smartdata.svDb()
+  public createdAt!: string;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: string;
+
+  @plugins.smartdata.svDb()
+  public account?: IFlexPublicAccountSummary;
+}
+
+@plugins.smartdata.managed({ collectionName: 'flex_model_choices' })
+export class FlexModelChoiceModel extends plugins.smartdata.SmartDataDbDoc<
+  FlexModelChoiceModel,
+  IFlexModelChoiceDocument
+> {
+  @plugins.smartdata.unI()
+  public id!: string;
+
+  @plugins.smartdata.index()
+  public controllerId!: string;
+
+  @plugins.smartdata.index()
+  public projectId!: string;
+
+  @plugins.smartdata.svDb()
+  public generation!: number;
+
+  @plugins.smartdata.svDb()
+  public choice!: IFlexModelChoice;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: string;
+}
+
+export const registerFlexPrivateModels = (
+  managerArg: { db: plugins.smartdata.SmartdataDb },
+): void => {
+  plugins.smartdata.setDefaultManagerForDoc(managerArg, FlexPrivateChunkModel);
+  plugins.smartdata.setDefaultManagerForDoc(managerArg, FlexPrivateCandidateModel);
+  plugins.smartdata.setDefaultManagerForDoc(managerArg, FlexHeadModel);
+  plugins.smartdata.setDefaultManagerForDoc(managerArg, FlexDomainHeadModel);
+  plugins.smartdata.setDefaultManagerForDoc(managerArg, FlexWriterLeaseModel);
+  plugins.smartdata.setDefaultManagerForDoc(managerArg, FlexMigrationModel);
+  plugins.smartdata.setDefaultManagerForDoc(managerArg, FlexProviderConnectionModel);
+  plugins.smartdata.setDefaultManagerForDoc(managerArg, FlexModelChoiceModel);
+};
+
+export const initFlexPrivateModels = async (): Promise<void> => {
+  await FlexPrivateChunkModel.init();
+  await FlexPrivateCandidateModel.init();
+  await FlexHeadModel.init();
+  await FlexDomainHeadModel.init();
+  await FlexWriterLeaseModel.init();
+  await FlexMigrationModel.init();
+  await FlexProviderConnectionModel.init();
+  await FlexModelChoiceModel.init();
+};