dsh-ptc-plus 0.4.8 → 0.5.0

package/internal/capability-plan.js

@@ -0,0 +1,285 @@
+import { capabilityRule, validateCapabilityPolicy, effectiveCapabilitySettings } from './capability-policy.js'
+import { Buffer } from 'node:buffer'
+
+const MANAGED_CATEGORIES = new Set(['tool', 'skill', 'resource', 'resource-template', 'task'])
+const EXCLUDED_CATEGORIES = new Set(['language', 'node', 'repl', 'ptc-plus', 'global-binding'])
+const SELECTIONS = new Set(['full', 'on-demand', 'closed'])
+const CATEGORY_NAVIGATION = new Map([
+  ['tool', 'Tools: search by task or tools.<name> for parameters and results.'],
+  ['skill', 'Skills: search by task or skills.<name> for when to use and how to load instructions.'],
+  ['resource', 'MCP resources: search by server or resource purpose.'],
+  ['resource-template', 'MCP templates: search by server or resource purpose.'],
+  ['task', 'Tasks: search by the operation you need.'],
+])
+
+function isRecord(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) }
+
+function record(value, label) {
+  if (!isRecord(value)) throw new TypeError(`ptc-plus: ${label} must be an object`)
+  return value
+}
+
+function text(value, label, empty = false) {
+  if (typeof value !== 'string' || (!empty && !value.trim())) throw new TypeError(`ptc-plus: ${label} must be a non-empty string`)
+  return value
+}
+
+function integer(value, label) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new TypeError(`ptc-plus: ${label} must be a non-negative integer`)
+  return value
+}
+
+function freeze(value) {
+  if (value && typeof value === 'object') {
+    for (const member of Object.values(value)) freeze(member)
+    Object.freeze(value)
+  }
+  return value
+}
+
+function compareIds(a, b) { return a.id < b.id ? -1 : a.id > b.id ? 1 : 0 }
+
+function catalog(entries, priority = () => 0) {
+  const dependencies = new Map()
+  const blocks = []
+  const groups = Map.groupBy([...entries].sort(compareIds), priority)
+  for (const [, group] of [...groups].sort(([a], [b]) => a - b)) {
+    const additions = new Map()
+    for (const entry of group) {
+      for (const dependency of entry.dependencies) {
+        const previous = dependencies.get(dependency.id) ?? additions.get(dependency.id)
+        if (previous !== undefined && previous !== dependency.text) throw new TypeError(`ptc-plus: conflicting shared contract ${dependency.id}`)
+        if (previous === undefined) additions.set(dependency.id, dependency.text)
+      }
+    }
+    for (const [id, body] of [...additions].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+      dependencies.set(id, body)
+      blocks.push(`### dependency:${id}\n${body}`)
+    }
+    blocks.push(...group.map(entry => `### ${entry.id}\n${entry.contract}`))
+  }
+  return blocks.join('\n\n')
+}
+
+function statisticsSettings(value) {
+  if (!value || value.enabled === false) return { usable: false, reason: 'statistics-disabled' }
+  if (value.enabled !== true || !Number.isSafeInteger(value.windowSize) || value.windowSize < 1
+    || !Number.isSafeInteger(value.minimumSamples) || value.minimumSamples < 1 || value.minimumSamples > value.windowSize
+    || !Number.isFinite(value.fullThreshold) || value.fullThreshold < 0 || value.fullThreshold > 1) {
+    return { usable: false, reason: 'statistics-settings-invalid' }
+  }
+  return { ...value, usable: true }
+}
+
+function coverage(value, settings) {
+  if (!isRecord(value) || value.status !== 'usable' || value.windowSize !== settings.windowSize
+    || !Number.isSafeInteger(value.eligible) || value.eligible < settings.minimumSamples || value.eligible > settings.windowSize
+    || !Number.isSafeInteger(value.used) || value.used < 0 || value.used > value.eligible) return null
+  return { used: value.used, eligible: value.eligible, coverage: value.used / value.eligible }
+}
+
+/** A frozen disclosure read model. It neither registers nor removes executable capabilities. */
+function createLegacyCapabilityPlan(input) {
+  const options = record(input, 'capability plan input')
+  const schema = 'ptc-capability-plan/v1'
+  if (typeof options.enabled !== 'boolean') throw new TypeError('ptc-plus: capability management enabled must be boolean')
+  const configurationRevision = text(options.configurationRevision, 'configuration revision')
+  if (!Array.isArray(options.capabilities)) throw new TypeError('ptc-plus: capabilities must be an array')
+  const ids = new Set()
+  const excluded = []
+  const capabilities = options.capabilities.map(raw => {
+    const value = record(raw, 'capability')
+    const id = text(value.id, 'capability id')
+    if (ids.has(id)) throw new TypeError(`ptc-plus: duplicate capability identity ${id}`)
+    ids.add(id)
+    const revision = text(value.revision, 'capability revision')
+    if (EXCLUDED_CATEGORIES.has(value.category)) {
+      excluded.push({ id, revision, category: value.category })
+      return null
+    }
+    if (!MANAGED_CATEGORIES.has(value.category)) throw new TypeError(`ptc-plus: unknown capability category ${value.category}`)
+    const dependencies = value.dependencies ?? []
+    if (!Array.isArray(dependencies)) throw new TypeError('ptc-plus: contract dependencies must be an array')
+    return {
+      id, revision, category: value.category,
+      ...(value.mcpServer === undefined ? {} : { mcpServer: text(value.mcpServer, 'MCP server identity') }),
+      ...(value.mcpServerCandidates === undefined ? {} : { mcpServerCandidates: value.mcpServerCandidates.map(server => text(server, 'MCP server candidate')) }),
+      contract: text(value.contract, 'complete capability contract'),
+      dependencies: dependencies.map(rawDependency => {
+        const dependency = record(rawDependency, 'contract dependency')
+        return { id: text(dependency.id, 'dependency id'), text: text(dependency.text, 'dependency contract') }
+      }),
+    }
+  }).filter(Boolean).sort(compareIds)
+  const bytes = value => Buffer.byteLength(value, 'utf8')
+  if (!options.enabled) return freeze({
+    schema, enabled: false, configurationRevision,
+    entries: capabilities.map(({ id, revision, category }) => ({ id, revision, category, selection: 'host', reason: 'management-disabled' })),
+    excluded: excluded.sort(compareIds), catalogText: '', directoryText: '',
+    budgets: { unit: 'utf8-bytes', contractBytes: 0, directoryBytes: 0, overageBytes: 0 },
+  })
+  const budgetBytes = integer(options.budgetBytes, 'contract budget bytes')
+  const directoryBudgetBytes = integer(options.directoryBudgetBytes, 'directory budget bytes')
+  const navigationText = text(options.navigationText, 'bounded discovery guidance')
+  if (bytes(navigationText) > directoryBudgetBytes) throw new RangeError('ptc-plus: discovery guidance exceeds directory byte budget')
+  const manual = record(options.manual ?? {}, 'manual capability settings')
+  const overrides = record(manual.overrides ?? {}, 'capability overrides')
+  const baseline = manual.baseline ?? []
+  if (!Array.isArray(baseline)) throw new TypeError('ptc-plus: initial common set must be an array')
+  baseline.forEach(id => text(id, 'baseline capability identity'))
+  const common = new Set(baseline)
+  for (const [id, selection] of Object.entries(overrides)) {
+    text(id, 'override capability identity')
+    if (!SELECTIONS.has(selection)) throw new TypeError(`ptc-plus: invalid capability selection ${selection}`)
+  }
+  const settings = statisticsSettings(options.statistics)
+  // Statistical damage cannot invalidate the independently valid manual configuration.
+  const statisticsInput = settings.usable ? options.coverage : undefined
+  const statistics = isRecord(statisticsInput) ? statisticsInput : null
+  const entries = []
+  const selections = new Map()
+  const full = []
+  const candidates = []
+  for (const capability of capabilities) {
+    if (capability.mcpServerCandidates?.some(server => overrides[`mcpServers.${server}`] === 'closed')) {
+      throw new TypeError(`ptc-plus: cannot determine the MCP server owner of ${capability.id}; conflicting namespaces: ${capability.mcpServerCandidates.join(', ')}`)
+    }
+    const serverClosed = capability.mcpServer !== undefined && overrides[`mcpServers.${capability.mcpServer}`] === 'closed'
+    const explicit = serverClosed ? 'closed' : Object.hasOwn(overrides, capability.id) ? overrides[capability.id] : undefined
+    const entry = { id: capability.id, revision: capability.revision, category: capability.category, selection: explicit ?? 'on-demand', reason: serverClosed ? 'mcp-server-disabled' : explicit ? 'manual-override' : 'baseline-not-selected' }
+    entries.push(entry)
+    selections.set(capability.id, entry)
+    if (explicit === 'full') full.push(capability)
+    if (explicit) continue
+    const evidence = statistics && Object.hasOwn(statistics, capability.id) ? statistics[capability.id] : undefined
+    let selectedCoverage = null
+    let source = settings.reason
+    if (settings.usable) {
+      if (isRecord(evidence) && evidence.revision === capability.revision) {
+        selectedCoverage = coverage(evidence.workspace, settings)
+        source = 'workspace'
+        if (!selectedCoverage) {
+          selectedCoverage = coverage(evidence.global, settings)
+          source = 'global'
+        }
+      }
+      if (!selectedCoverage) source = statisticsInput !== undefined && !statistics ? 'statistics-data-invalid' : 'statistics-unavailable'
+    }
+    entry.statisticsReason = source
+    if (selectedCoverage) {
+      entry.evidence = { scope: source, ...selectedCoverage }
+      entry.reason = 'coverage-below-threshold'
+      if (selectedCoverage.coverage >= settings.fullThreshold) candidates.push({ capability, entry, weight: selectedCoverage.coverage })
+    } else if (common.has(capability.id)) {
+      entry.reason = 'baseline'
+      candidates.push({ capability, entry, weight: 1 })
+    }
+  }
+  // Whole blocks and shared type identities reproduce the final renderer's exact byte cost.
+  const includedDependencies = new Map()
+  let blockCount = 0
+  let blockBytes = 0
+  function addCost(capability, commit) {
+    let count = blockCount + 1
+    let size = blockBytes + bytes(`### ${capability.id}\n${capability.contract}`)
+    const additions = new Map()
+    for (const dependency of capability.dependencies) {
+      const previous = additions.get(dependency.id) ?? includedDependencies.get(dependency.id)
+      if (previous !== undefined && previous !== dependency.text) throw new TypeError(`ptc-plus: conflicting shared contract ${dependency.id}`)
+      if (previous === undefined) {
+        additions.set(dependency.id, dependency.text)
+        size += bytes(`### dependency:${dependency.id}\n${dependency.text}`)
+        count++
+      }
+    }
+    if (commit) {
+      for (const [id, body] of additions) includedDependencies.set(id, body)
+      blockCount = count
+      blockBytes = size
+    }
+    return size + Math.max(0, count - 1) * 2
+  }
+  for (const capability of full) addCost(capability, true)
+  // Ranking includes actual UTF-8 wrappers and dependencies, not capability counts.
+  for (const candidate of candidates) candidate.cost = Math.max(1, bytes(catalog([candidate.capability])))
+  candidates.sort((a, b) => {
+    return b.weight / b.cost - a.weight / a.cost || compareIds(a.capability, b.capability)
+  })
+  for (const candidate of candidates) {
+    if (addCost(candidate.capability, false) <= budgetBytes) {
+      addCost(candidate.capability, true)
+      full.push(candidate.capability)
+      candidate.entry.selection = 'full'
+      candidate.entry.reason = candidate.entry.evidence ? 'statistical-coverage' : 'baseline'
+    } else candidate.entry.reason = 'contract-budget'
+  }
+  // Statistics choose membership, never the order of unchanged contract groups.
+  const catalogText = catalog(full,
+    capability => overrides[capability.id] === 'full' ? 0 : common.has(capability.id) ? 1 : 2)
+  let directoryText = navigationText
+  const directoryCategories = []
+  const availableCategories = new Set(capabilities.filter(capability => selections.get(capability.id).selection !== 'closed')
+    .map(capability => capability.category))
+  for (const [category, guidance] of CATEGORY_NAVIGATION) {
+    if (!availableCategories.has(category)) continue
+    const proposed = `${directoryText}\n${guidance}`
+    if (bytes(proposed) <= directoryBudgetBytes) {
+      directoryText = proposed
+      directoryCategories.push(category)
+    }
+  }
+  return freeze({
+    schema, enabled: true, configurationRevision, entries,
+    excluded: excluded.sort(compareIds), catalogText, directoryText, directoryCategories,
+    budgets: { unit: 'utf8-bytes', budgetBytes, directoryBudgetBytes, contractBytes: bytes(catalogText), directoryBytes: bytes(directoryText), overageBytes: Math.max(0, bytes(catalogText) - budgetBytes) },
+    unresolvedConfigurationIds: [...new Set([...baseline, ...Object.keys(overrides)])].filter(id => !capabilities.some(entry => entry.id === id)).sort(),
+    statisticsStatus: settings.usable ? 'enabled' : settings.reason,
+  })
+}
+
+/** The old planner remains the replay oracle for environment v1/v2. */
+export function createCapabilityPlan(input) {
+  if (input.contextEnabled !== undefined) {
+    if (typeof input.contextEnabled !== 'boolean') throw new TypeError('ptc-plus: capability context enabled must be boolean')
+    const effective = effectiveCapabilitySettings(input)
+    const { contextEnabled, ...historicalInput } = effective
+    return freeze({ ...createCapabilityPlan(historicalInput), schema: 'ptc-capability-plan/v3', contextEnabled })
+  }
+  if (input.policy === undefined) return createLegacyCapabilityPlan(input)
+  const policy = validateCapabilityPolicy(input.policy)
+  const rules = new Map(input.capabilities.filter(item => MANAGED_CATEGORIES.has(item.category))
+    .map(item => {
+      const rule = input.enabled ? capabilityRule(policy, item) : { availability: 'enabled', disclosure: 'host', availabilitySource: 'host', disclosureSource: 'host' }
+      return [item.id, item.effectiveAvailability === 'closed'
+        ? { ...rule, availability: 'closed', availabilitySource: 'invocation-path' } : rule]
+    }))
+  const mixedSkills = input.enabled && input.capabilities.some(item => item.category === 'skill'
+    && rules.get(item.id)?.availability !== 'closed' && (rules.get(item.id)?.disclosure !== 'host' || item.nativeInvocation !== undefined))
+  const overrides = Object.fromEntries([...rules].flatMap(([id, rule]) => rule.availability === 'closed'
+    ? [[id, 'closed']] : rule.disclosure === 'adaptive' ? []
+      : [[id, rule.disclosure === 'host' ? mixedSkills && input.capabilities.find(item => item.id === id)?.category === 'skill' ? 'full' : 'on-demand' : rule.disclosure]]))
+  const planned = createLegacyCapabilityPlan({ ...input,
+    budgetBytes: policy.allocation.budget ? input.budgetBytes : Number.MAX_SAFE_INTEGER,
+    manual: { baseline: policy.allocation.baseline ? input.manual?.baseline ?? [] : [], overrides },
+    statistics: policy.allocation.statistics ? { ...input.statistics, enabled: true } : { enabled: false },
+  })
+  const entries = planned.entries.map(entry => {
+    const rule = rules.get(entry.id)
+    const selection = rule.availability === 'closed' ? 'closed' : !input.enabled || rule.disclosure === 'host' ? 'host' : entry.selection
+    return { ...entry, ...rule, selection,
+      availability: rule.availability,
+      disclosure: !input.enabled ? 'host' : rule.disclosure,
+      ...((selection === 'host' && input.enabled) ? { reason: 'host-disclosure' }
+        : rule.availability === 'closed' ? { reason: rule.availabilitySource.startsWith('mcp:') ? 'mcp-server-disabled' : 'availability-rule' }
+          : rule.disclosure !== 'adaptive' && input.enabled ? { reason: 'disclosure-rule' } : {}) }
+  })
+  // Navigation is needed only for deliberately deferred explanations.
+  const onDemand = entries.some(entry => entry.selection === 'on-demand')
+  return freeze({ ...planned, schema: 'ptc-capability-plan/v2', entries,
+    directoryText: onDemand ? planned.directoryText : '', directoryCategories: onDemand ? planned.directoryCategories : [],
+    budgets: { ...planned.budgets, ...(input.enabled ? { budgetBytes: input.budgetBytes } : {}),
+      directoryBytes: onDemand ? planned.budgets.directoryBytes : 0,
+      overageBytes: input.enabled ? Math.max(0, planned.budgets.contractBytes - input.budgetBytes) : 0 },
+    ...(input.enabled ? { unresolvedConfigurationIds: [...new Set([...(input.manual?.baseline ?? []), ...Object.keys(policy.items)])]
+      .filter(id => !input.capabilities.some(item => item.id === id)).sort(), allocation: policy.allocation } : {}) })
+}

package/internal/capability-policy.js

@@ -0,0 +1,96 @@
+/** Reusable user intent; no inventory, observations, authority or session state. */
+export const CAPABILITY_POLICY_DEFAULT = JSON.stringify({
+  schema: 'ptc-capability-policy/v1',
+  defaults: { availability: 'enabled', disclosure: 'host' },
+  categories: {}, mcpServers: {}, items: {},
+  allocation: { baseline: true, statistics: false, budget: true },
+})
+
+/** Categories produced by the current Host integration; resources and templates share a server entry. */
+export const CAPABILITY_INVENTORY_CATEGORIES = Object.freeze({ tool: 'tool', skill: 'skill', resource: 'resource' })
+// The configuration format also accepts independent template/task entries supplied to the pure planner.
+export const CAPABILITY_CATEGORIES = [...Object.values(CAPABILITY_INVENTORY_CATEGORIES), 'resource-template', 'task']
+export const CAPABILITY_DISCLOSURES = ['host', 'full', 'on-demand', 'adaptive']
+const isRecord = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+const own = (value, key) => Object.hasOwn(value, key) ? value[key] : undefined
+
+/** The group pauses application, never the retained independent choices. Missing denotes historical behavior. */
+export function effectiveCapabilitySettings(settings) {
+  if (settings.contextEnabled !== false) return settings
+  return { ...settings, enabled: false, recoveryEnabled: false, previewEnabled: false,
+    statistics: { ...settings.statistics, enabled: false } }
+}
+
+export function validateCapabilityPolicy(value) {
+  const fail = () => { throw new TypeError('ptc-plus: invalid capability policy') }
+  if (!isRecord(value) || value.schema !== 'ptc-capability-policy/v1'
+    || Object.keys(value).some(key => !['schema', 'defaults', 'categories', 'mcpServers', 'items', 'allocation'].includes(key))) fail()
+  function rule(value, defaults = false) {
+    if (!isRecord(value) || Object.keys(value).some(key => !['availability', 'disclosure'].includes(key))
+      || (own(value, 'availability') !== undefined && !['enabled', 'closed'].includes(value.availability))
+      || (own(value, 'disclosure') !== undefined && !CAPABILITY_DISCLOSURES.includes(value.disclosure))
+      || defaults && (value.availability === undefined || value.disclosure === undefined)) fail()
+    return { ...(value.availability === undefined ? {} : { availability: value.availability }),
+      ...(value.disclosure === undefined ? {} : { disclosure: value.disclosure }) }
+  }
+  const rules = (values, valid) => {
+    if (!isRecord(values)) fail()
+    return Object.fromEntries(Object.entries(values).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+      .map(([id, value]) => { if (!valid(id)) fail(); return [id, rule(value)] }))
+  }
+  if (!isRecord(value.allocation) || Object.keys(value.allocation).length !== 3
+    || ['baseline', 'statistics', 'budget'].some(key => typeof value.allocation[key] !== 'boolean')) fail()
+  return { schema: value.schema, defaults: rule(value.defaults, true),
+    categories: rules(value.categories, id => CAPABILITY_CATEGORIES.includes(id)),
+    mcpServers: rules(value.mcpServers, id => Boolean(id.trim())),
+    items: rules(value.items, id => Boolean(id.trim()) && !id.startsWith('mcpServers.')),
+    allocation: { baseline: value.allocation.baseline, statistics: value.allocation.statistics, budget: value.allocation.budget } }
+}
+
+/** Missing policy denotes the previous configuration format, not a new default. */
+export function capabilityPolicyForConfig(config) {
+  if (config.capabilityPolicy !== undefined) return validateCapabilityPolicy(JSON.parse(config.capabilityPolicy))
+  const policy = JSON.parse(CAPABILITY_POLICY_DEFAULT)
+  if (config.capabilityManagementEnabled === true) policy.defaults.disclosure = 'adaptive'
+  try { policy.allocation.statistics = JSON.parse(config.capabilityStatistics ?? '{}')?.enabled === true } catch {}
+  const overrides = JSON.parse(config.capabilityOverrides ?? '{}')
+  for (const [id, choice] of Object.entries(overrides)) {
+    const rule = choice === 'closed' ? { availability: 'closed' } : { disclosure: choice }
+    const rules = id.startsWith('mcpServers.') ? policy.mcpServers : policy.items
+    const key = id.startsWith('mcpServers.') ? id.slice(11) : id
+    Object.defineProperty(rules, key, { value: rule, enumerable: true, writable: true, configurable: true })
+  }
+  return validateCapabilityPolicy(policy)
+}
+
+/** Independent dimensions preserve the rule that supplied each decision. */
+export function capabilityRule(policy, capability) {
+  let availability = policy.defaults.availability, disclosure = policy.defaults.disclosure
+  let availabilitySource = 'default', disclosureSource = 'default'
+  const server = capability.mcpServer === undefined ? undefined : own(policy.mcpServers, capability.mcpServer)
+  const apply = (rule, source) => {
+    if (rule?.availability !== undefined) { availability = rule.availability; availabilitySource = source }
+    if (rule?.disclosure !== undefined) { disclosure = rule.disclosure; disclosureSource = source }
+  }
+  apply(own(policy.categories, capability.category), `category:${capability.category}`)
+  apply(server, `mcp:${capability.mcpServer}`)
+  apply(own(policy.items, capability.id), `item:${capability.id}`)
+  if (server?.availability === 'closed') { availability = 'closed'; availabilitySource = `mcp:${capability.mcpServer}` }
+  if (capability.mcpServerCandidates?.some(id => own(policy.mcpServers, id)?.availability === 'closed')) {
+    throw new TypeError(`ptc-plus: cannot determine the MCP server owner of ${capability.id}; conflicting namespaces: ${capability.mcpServerCandidates.join(', ')}`)
+  }
+  return { availability, disclosure, availabilitySource, disclosureSource }
+}
+
+/** Change one reusable dimension, removing only that dimension for automatic. */
+export function changeCapabilityRule(policy, id, dimension, choice) {
+  const next = structuredClone(policy)
+  const rules = id.startsWith('mcpServers.') ? next.mcpServers : next.items
+  const key = id.startsWith('mcpServers.') ? id.slice(11) : id
+  const rule = { ...own(rules, key) }
+  if (choice === 'automatic') delete rule[dimension]
+  else rule[dimension] = choice
+  if (Object.keys(rule).length) Object.defineProperty(rules, key, { value: rule, enumerable: true, writable: true, configurable: true })
+  else delete rules[key]
+  return validateCapabilityPolicy(next)
+}

package/internal/capability-statistics-store.js

@@ -0,0 +1,180 @@
+import { effectiveCapabilitySettings } from './capability-policy.js'
+import { createHash } from 'node:crypto'
+import { mkdir, readFile } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths'
+import { capabilityCoverage, createCapabilityStatistics, reduceCapabilityStatistics, validateCapabilityStatistics } from './capability-statistics.js'
+
+const hash = value => createHash('sha256').update(value).digest('hex')
+const evidence = { tool: 'host-execution-result', task: 'host-execution-result', skill: 'skill-body-accepted', resource: 'resource-access', 'resource-template': 'resource-access' }
+
+/** Locked metadata only; never persists arguments, results, resource contents or Skill bodies. */
+export class CapabilityStatisticsStore {
+  constructor({ filename, ctx, dshHome } = {}) {
+    this.filename = resolve(filename ?? join(resolveDshHome(dshHome), 'ptc-plus', 'capability-statistics.json'))
+    this.userId = hash(dirname(this.filename))
+    this.ctx = ctx
+    this.tail = Promise.resolve()
+  }
+
+  async read(windowSize) {
+    let value
+    try { value = JSON.parse(await readFile(this.filename, 'utf8')) } catch (error) {
+      if (error.code !== 'ENOENT') throw error
+      return { schema: 'ptc-capability-statistics-store/v1', nextOrder: 1, members: [], families: [],
+        state: createCapabilityStatistics({ windowSize, maxFamilies: 10000, maxScopes: 20000, maxCapabilitiesPerFamily: 2000 }) }
+    }
+    if (value?.schema !== 'ptc-capability-statistics-store/v1' || !Array.isArray(value.members)
+      || !Array.isArray(value.families) || value.families.length > 10000
+      || value.members.length > 10000 || !Number.isSafeInteger(value.nextOrder) || value.nextOrder < 1) throw new TypeError('damaged capability statistics store')
+    validateCapabilityStatistics(value.state)
+    const identities = new Set()
+    const orders = new Set()
+    for (const family of value.families) {
+      if (typeof family?.id !== 'string' || !family.id.trim() || identities.has(family.id)
+        || !Number.isSafeInteger(family.observationRevision) || family.observationRevision < 0
+        || (family.eligibleOrder !== null && (!Number.isSafeInteger(family.eligibleOrder)
+          || family.eligibleOrder < 1 || family.eligibleOrder >= value.nextOrder || orders.has(family.eligibleOrder)))) {
+        throw new TypeError('damaged capability statistics family provenance')
+      }
+      identities.add(family.id)
+      if (family.eligibleOrder !== null) orders.add(family.eligibleOrder)
+    }
+    for (const retained of value.state.families) {
+      const family = value.families.find(item => item.id === retained.familyId)
+      if (retained.userId !== this.userId || !family || (value.state.status === 'usable'
+        && (family.eligibleOrder !== retained.eligibleOrder || family.observationRevision !== retained.observationRevision))) {
+        throw new TypeError('inconsistent capability statistics family provenance')
+      }
+    }
+    if (value.state.windows.some(window => window.userId !== this.userId || window.floor >= value.nextOrder)) {
+      throw new TypeError('inconsistent capability statistics qualification frontier')
+    }
+    for (const member of value.members) {
+      if (typeof member.id !== 'string' || typeof member.familyId !== 'string' || !identities.has(member.familyId)
+        || !['active', 'settled', 'unknown'].includes(member.status)) throw new TypeError('damaged capability statistics member')
+    }
+    if (new Set(value.members.map(item => item.id)).size !== value.members.length) throw new TypeError('duplicate capability statistics member')
+    if (value.state.limits.windowSize !== windowSize) throw new TypeError('statistics window changed; retained samples are unavailable')
+    return value
+  }
+
+  family(agent) {
+    let session = agent.session
+    const visited = new Set()
+    while (session.header?.origin === 'subagent' && session.header?.parentSession) {
+      if (visited.has(session.id)) return null
+      visited.add(session.id)
+      session = this.ctx?.get('sessions')?.get?.(session.header.parentSession)
+        ?? this.ctx?.get('agents')?.get?.(session.header.parentSession)?.session
+      if (!session) return null
+    }
+    return session.id
+  }
+
+  memberSettlement(session, live) {
+    if (live && live.status !== 'idle') return 'active'
+    const events = session.snapshotEvents().filter(event => session.isOwnSeq?.(event.seq) !== false)
+    const start = events.findLast(event => event.type === 'turn/start')
+    if (!start) return 'unknown'
+    const end = events.findLast(event => event.type === 'turn/end' && event.data.turn === start.data.turn)
+    const entered = events.some(event => event.type === 'step/start' && event.data.turn === start.data.turn)
+    if (!end) return live ? 'active' : 'unknown'
+    if (end.data.reason?.kind !== 'completed' || !entered) return 'unknown'
+    if (live?.inbox?.nextStep?.length || live?.inbox?.nextTurn?.length) return 'active'
+    return 'settled'
+  }
+
+  mutate(agent, snapshot, additions = [], status = 'active') {
+    const settings = effectiveCapabilitySettings(snapshot.settings).statistics
+    if (!snapshot.settings.policy && !snapshot.plan.enabled || settings?.enabled !== true || !Number.isSafeInteger(settings.windowSize)
+      || settings.windowSize < 1 || settings.windowSize > 10000) return Promise.resolve()
+    const familyId = this.family(agent)
+    if (!familyId) return Promise.resolve()
+    const operation = async () => {
+      await mkdir(dirname(this.filename), { recursive: true, mode: 0o700 })
+      return withFileLock(this.filename, async () => {
+        const document = await this.read(settings.windowSize)
+        if (document.state.status !== 'usable') return
+        const retained = structuredClone(document)
+        const capacityExceeded = async () => {
+          retained.state.status = 'capacity-exceeded'
+          await writeFileAtomic(this.filename, JSON.stringify(retained) + '\n', { mode: 0o600, dirMode: 0o700 })
+        }
+        if (additions.length > document.state.limits.maxCapabilitiesPerFamily) return capacityExceeded()
+        const liveAgents = this.ctx?.get('agents')?.list?.()
+        const sessions = this.ctx?.get('sessions')?.list?.()
+        const completeCensus = Array.isArray(liveAgents) && Array.isArray(sessions)
+        const known = new Map((sessions ?? []).map(session => [session.id, session]))
+        for (const live of liveAgents ?? []) known.set(live.session.id, live.session)
+        known.set(agent.session.id, agent.session)
+        for (const session of known.values()) {
+          if (this.family({ session }) !== familyId) continue
+          let member = document.members.find(item => item.id === session.id)
+          if (!member) { member = { id: session.id, familyId, status: 'unknown' }; document.members.push(member) }
+          if (member.familyId !== familyId) throw new TypeError('capability statistics lineage changed')
+          const live = (liveAgents ?? []).find(item => item.session.id === session.id)
+          member.status = completeCensus ? this.memberSettlement(session, live) : 'unknown'
+          if (session.id === agent.session.id && status !== 'idle') member.status = 'active'
+        }
+        // A missing descendant or an incomplete public census cannot establish
+        // a family denominator, even if every observed agent currently is idle.
+        for (const member of document.members.filter(item => item.familyId === familyId)) {
+          if (!known.has(member.id)) member.status = 'unknown'
+        }
+        const familyMembers = document.members.filter(item => item.familyId === familyId)
+        const settlement = familyMembers.every(item => item.status === 'settled') ? 'settled'
+          : familyMembers.some(item => item.status === 'unknown') ? 'unknown' : 'active'
+        // Window eviction removes sample payloads, never the immutable family
+        // qualification or revision used by restored and concurrent observers.
+        let provenance = document.families.find(item => item.id === familyId)
+        if (!provenance) {
+          provenance = { id: familyId, observationRevision: -1, eligibleOrder: null }
+          document.families.push(provenance)
+        }
+        if (document.families.length > 10000 || provenance.observationRevision >= Number.MAX_SAFE_INTEGER
+          || document.nextOrder >= Number.MAX_SAFE_INTEGER) return capacityExceeded()
+        provenance.eligibleOrder ??= settlement === 'settled' ? document.nextOrder++ : null
+        provenance.observationRevision++
+        document.state = reduceCapabilityStatistics(document.state, { type: 'family-observation', userId: this.userId, familyId,
+          observationRevision: provenance.observationRevision, settlement, eligibleOrder: provenance.eligibleOrder, observations: additions })
+        if (document.members.length > 10000) return capacityExceeded()
+        await writeFileAtomic(this.filename, JSON.stringify(document) + '\n', { mode: 0o600, dirMode: 0o700 })
+      })
+    }
+    const task = this.tail.then(operation, operation)
+    this.tail = task.catch(() => {})
+    return task
+  }
+
+  observations(agent, snapshot, id, useEvidence = null, outcome = null) {
+    const workspaceId = hash(resolve(agent.session.header.cwd))
+    return snapshot.plan.entries.filter(entry => ['full', 'on-demand', 'host'].includes(entry.selection)
+      && (id === undefined || entry.id === id)).map(entry => ({ workspaceId,
+      id: entry.id, revision: entry.revision, category: entry.category, disclosure: entry.selection,
+      planRevision: snapshot.plan.configurationRevision, useEvidence, outcome }))
+  }
+
+  available(agent, snapshot) { return this.mutate(agent, snapshot, this.observations(agent, snapshot)) }
+  used(agent, snapshot, id, useEvidence, outcome) {
+    const entry = snapshot.plan.entries.find(item => item.id === id)
+    if (!entry || evidence[entry.category] !== useEvidence) return Promise.resolve()
+    return this.mutate(agent, snapshot, this.observations(agent, snapshot, id, useEvidence, outcome))
+  }
+  status(agent, snapshot, status) { return this.mutate(agent, snapshot, [], status) }
+
+  async coverage(agent, capabilities, settings) {
+    try {
+      await this.tail
+      const { state } = await this.read(settings.windowSize)
+      const workspaceId = hash(resolve(agent.session.header.cwd))
+      return Object.fromEntries(capabilities.map(item => [item.id, { revision: item.revision,
+        workspace: capabilityCoverage(state, { userId: this.userId, workspaceId, id: item.id, revision: item.revision }),
+        global: capabilityCoverage(state, { userId: this.userId, workspaceId: null, id: item.id, revision: item.revision }) }]))
+    } catch (error) {
+      this.ctx?.logger?.warn?.('ptc-plus: automatic allocation unavailable; retaining manual capability settings', error)
+      return null
+    }
+  }
+}