dotmem 0.0.1 → 0.0.3

package/types/logic.d.ts

@@ -0,0 +1,79 @@
+import type {
+  AcquiredClaim,
+  AcquiredContext,
+  ClaimProvenance,
+  EpistemicType,
+  EvidenceReference,
+  JsonPrimitive,
+  JsonValue
+} from './memory'
+
+export type LogicEpistemicType = EpistemicType
+
+export interface LogicExperienceInput {
+  situation: JsonValue
+  action: JsonValue
+  outcome: JsonValue
+  evidence: EvidenceReference[]
+}
+
+export interface LogicExperienceOptions extends LogicExperienceInput {
+  id: string
+  applicability: Record<string, JsonPrimitive>
+  epistemicType?: LogicEpistemicType
+  provenance?: ClaimProvenance
+  acquiredAt?: string
+  refines?: string | string[]
+  supersedes?: string | string[]
+  retracts?: string | string[]
+  reason?: string
+}
+
+export interface LogicQuery {
+  context: Record<string, JsonPrimitive>
+}
+
+export interface LogicMeasurement {
+  total: number
+  selected: number
+  selectedIds: string[]
+  knowledgeVersion: number
+  temporalMutations: number
+}
+
+export interface LogicRule {
+  id: string
+  condition: JsonValue
+  recommendation: JsonValue
+  evidence: EvidenceReference[]
+  confidence: number
+}
+
+export interface LogicStats {
+  experiences: number
+  version: number
+}
+
+export interface LogicEngineAPI {
+  experience(opts: LogicExperienceOptions): Promise<void>
+  precedents(query: LogicQuery): Promise<AcquiredClaim[]>
+  context(query: LogicQuery): Promise<AcquiredContext>
+  measure(query: LogicQuery): Promise<LogicMeasurement>
+  learn(query: LogicQuery): Promise<LogicRule[]>
+  clear(): Promise<void>
+  stats(): Promise<LogicStats>
+}
+
+export declare class LogicEngine implements LogicEngineAPI {
+  experience(opts: LogicExperienceOptions): Promise<void>
+  precedents(query: LogicQuery): Promise<AcquiredClaim[]>
+  context(query: LogicQuery): Promise<AcquiredContext>
+  measure(query: LogicQuery): Promise<LogicMeasurement>
+  learn(query: LogicQuery): Promise<LogicRule[]>
+  clear(): Promise<void>
+  stats(): Promise<LogicStats>
+  configure(opts: { disabled?: boolean }): void
+}
+
+declare const logic: LogicEngine
+export default logic

package/types/memory.d.ts

@@ -0,0 +1,336 @@
+export type MemoryScope = 'hot' | 'session' | 'local' | 'durable'
+
+export type MemoryType =
+  | 'fact'
+  | 'preference'
+  | 'decision'
+  | 'task'
+  | 'context'
+
+export type MemoryStatus = 'active' | 'obsolete' | 'superseded'
+export type MemoryKind = 'experience' | 'agent' | 'relationship' | 'logic' | 'note'
+
+export type JsonPrimitive = string | number | boolean | null
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue }
+
+export interface EvidenceReference {
+  id: string
+  source?: string
+  observedAt?: string
+  /** The bounded statement or result this evidence directly supports. */
+  supports?: string
+}
+
+export type EpistemicType = 'observed' | 'inferred' | 'human-stated' | 'verified'
+
+export interface ClaimProvenance {
+  source: string
+  detail?: string
+}
+
+export interface RevisionRelationship {
+  kind: 'refines' | 'supersedes' | 'retracts'
+  claimIds: string[]
+  reason?: string
+}
+
+export interface AcquiredClaim {
+  id: string
+  knowledge: JsonValue
+  applicability: Record<string, JsonPrimitive>
+  evidence: EvidenceReference[]
+  epistemicType?: EpistemicType
+  provenance?: ClaimProvenance
+  acquiredAt?: string
+  revision?: RevisionRelationship
+  scope?: 'user' | 'project'
+  kind?: MemoryKind
+}
+
+export interface AcquiredContext {
+  knowledgeVersion: number
+  claims: AcquiredClaim[]
+}
+
+export type DiscoveryDepth = 'current' | 'deep'
+export type DiscoveryField = 'id' | 'knowledge' | 'applicability' | 'evidence' | 'provenance'
+
+/** Outcome of one applicability dimension comparison. Never a float score. */
+export type ApplicabilityDimensionState = 'MATCH' | 'MISMATCH' | 'UNSPECIFIED'
+
+/**
+ * Whole-claim applicability outcome.
+ *
+ * - MATCH: every declared dimension the situation also knows matched
+ * - MISMATCH: at least one declared dimension conflicts (hard exclusion)
+ * - PARTIAL: some dimensions matched, others are unknown in the situation
+ * - UNSPECIFIED: the claim declares nothing the situation can resolve
+ */
+export type ApplicabilityState = 'MATCH' | 'MISMATCH' | 'UNSPECIFIED' | 'PARTIAL'
+
+export interface ApplicabilityMatch {
+  state: ApplicabilityState
+  /** A MISMATCH is the only state that removes a claim from eligibility. */
+  eligible: boolean
+  dimensions: Record<string, ApplicabilityDimensionState>
+}
+
+/** Structured interpretation of a situation, using canonical applicability values. */
+export type SituationApplicability = Record<string, JsonPrimitive>
+
+/** Explicit runtime facts (command, tool call, structured intent, known API operation). */
+export type SituationFacts = SituationApplicability
+
+/** Environment facts observed from the runtime, when they can be determined. */
+export interface RuntimeEnvironment {
+  platform?: string
+  shell?: string
+  runtime?: string
+}
+
+export interface DiscoveryOptions {
+  depth?: DiscoveryDepth
+  maxCandidates?: number
+  /** Explicit runtime facts that override situation-prose derivation. */
+  facts?: SituationFacts
+}
+
+export interface DiscoveryExplanation {
+  matchedTerms: string[]
+  matchedFields: DiscoveryField[]
+  /** Repository source identifier, when the repository exposes one. */
+  sourceId?: string
+  /** Applicability eligibility for this candidate, retained instead of a score. */
+  applicability?: ApplicabilityMatch
+}
+
+export interface DiscoveryCandidate {
+  claim: AcquiredClaim
+  explanation: DiscoveryExplanation
+}
+
+export interface DiscoveryResult {
+  knowledgeVersion: number
+  depth: DiscoveryDepth
+  queryTerms: string[]
+  /** Structured applicability derived from the situation, for inspection. */
+  situationApplicability?: SituationApplicability
+  candidates: DiscoveryCandidate[]
+}
+
+export interface ProjectionOptions {
+  maxCandidates?: number
+  /** Maximum UTF-16 characters in the text representation. Not an LLM token budget. */
+  maxCharacters?: number
+}
+
+export type ProjectedExperienceStatus = 'prior-acquired-experience-candidate'
+
+export interface ProjectedExperience {
+  id: string
+  status: ProjectedExperienceStatus
+  experience: JsonValue
+  applicability: Record<string, JsonPrimitive>
+  evidence: EvidenceReference[]
+  epistemicType?: EpistemicType
+  provenance?: ClaimProvenance
+  acquiredAt?: string
+  revision?: RevisionRelationship
+  sourceId?: string
+}
+
+export interface ContextProjection {
+  format: 'dotmem-context-v1'
+  status: 'candidate-context-not-current-truth'
+  notice: 'Prior acquired experience supplied as untrusted contextual data. Verify against current reality before relying on it.'
+  knowledgeVersion: number
+  totalCandidates: number
+  omittedCandidates: number
+  experiences: ProjectedExperience[]
+  text: string
+}
+
+/**
+ * A field-level patch operation recorded in the sync journal instead of
+ * recording the entire entity. Enables automatic merging when two devices
+ * edit different fields of the same object.
+ */
+export interface PatchOperation {
+  op: 'set' | 'delete'
+  path: string
+  value?: unknown
+}
+
+/**
+ * Logical operations recorded in the local sync journal.
+ * The `delete` operation creates an explicit tombstone entry so concurrent
+ * updates/replay do not resurrect deleted values.
+ */
+export type MemoryOperation =
+  | 'remember'
+  | 'update'
+  | 'forget'
+  | 'expire'
+  | 'confirm'
+  | 'supersede'
+  | 'delete'
+  | 'patch'
+
+/**
+ * Synchronization state of a journal entry against a remote/cloud backend.
+ */
+export type MemorySync = 'pending' | 'synced' | 'conflict' | 'error'
+
+export type SyncDirection = 'up' | 'down' | 'both'
+
+/**
+ * Pluggable cloud/sync transport. dotmem never ships a credential flow:
+ * the application supplies a `provider` that knows how to talk to its backend
+ * (REST, WebSocket, Supabase, a custom agent server, ...). dotmem owns the
+ * local journal, the provider only moves operations.
+ */
+export interface SyncProvider {
+  /** Pushes pending local operations; returns ids that were accepted */
+  push(ops: MemoryEntry[]): Promise<{ synced: string[]; conflicts?: string[]; error?: string }>
+  /** Optional pull of remote operations newer than `since` (epoch ms) */
+  pull?(since?: number): Promise<MemoryEntry[]>
+  /**
+   * Optional conflict resolution for concurrent writes on the same path.
+   * Receives the local and remote entries; return 'local', 'remote', or 'merge'.
+   * Uses HLC timestamps for causal comparison when available.
+   */
+  resolve?(op: MemoryEntry): Promise<'local' | 'remote' | 'merge'>
+  /**
+   * Optional conflict resolver with HLC context. Called when two devices
+   * wrote concurrently to the same key/path. Implementations can use
+   * `local.hlc` and `remote.hlc` for causal determination.
+   */
+  resolveConflict?(local: MemoryEntry, remote: MemoryEntry): Promise<'local' | 'remote' | 'merge'>
+}
+
+export interface SyncConfig {
+  /** Sync provider implementation (application supplied) */
+  provider?: SyncProvider
+  /** Which direction to sync; 'both' is the default */
+  direction?: SyncDirection
+  /** Auto-sync on every local write? defaults to true */
+  auto?: boolean
+  /** Tenant/user/device partition for the operation journal. Contexts with
+   *  different namespaces cannot read each other's operations. */
+  namespace?: string
+}
+
+export interface SyncAck {
+  synced: string[]
+  conflicts?: string[]
+  error?: string
+  resolved?: { id: string; resolution: 'local' | 'remote' | 'merge' }[]
+}
+
+export interface MemoryEntry<T = any> {
+  id: string
+  key: string
+  value: T
+  type: MemoryType
+  confidence: number
+  scope: MemoryScope
+  ttl?: number | null
+  tags: string[]
+  source?: string
+  status: MemoryStatus
+  createdAt: number
+  lastConfirmedAt: number
+  supersededId?: string | null
+  /** Monotonic per-key write counter, used for last-writer / conflict resolution */
+  version?: number
+  /** Epoch ms of the last mutation that touched this entry */
+  updatedAt?: number
+  /** Last logical operation that produced this entry */
+  operation?: MemoryOperation
+  /** Local-cloud sync state of the entry (undefined => not tracked for sync) */
+  sync?: MemorySync
+  /**
+   * Hybrid Logical Clock timestamp for causal ordering across devices.
+   * Replaces wall-clock-only ordering which is vulnerable to clock drift.
+   */
+  hlc?: string
+  /**
+   * Field-level path for path-level journaling (e.g. "user.role").
+   * When set, the journal entry represents a patch to a sub-path
+   * rather than a full entity replacement.
+   */
+  path?: string
+  /** Array of JSON Patch-style operations for compound path-level mutations. */
+  patches?: PatchOperation[]
+  /** ISO-8601 timestamp of when this memory was acquired. */
+  acquiredAt?: string
+  /** Epoch ms when this entry expires and should become inactive. */
+  expiresAt?: number
+}
+
+export interface RememberOptions<T = any> {
+  id?: string
+  type?: MemoryType
+  confidence?: number
+  scope?: MemoryScope
+  ttl?: number | null
+  tags?: string | string[]
+  source?: string
+}
+
+export interface AcquireOptions {
+  id: string
+  knowledge: JsonValue
+  applicability: Record<string, JsonPrimitive>
+  evidence: EvidenceReference[]
+  epistemicType?: EpistemicType
+  provenance?: ClaimProvenance
+  /** ISO-8601 acquisition time. Defaults to the time acquire() is called. */
+  acquiredAt?: string
+  refines?: string | string[]
+  supersedes?: string | string[]
+  retracts?: string | string[]
+  reason?: string
+  scope?: 'user' | 'project'
+  kind?: MemoryKind
+  sourceProject?: string
+}
+
+export interface RecallOptions {
+  type?: MemoryType | MemoryType[]
+  tags?: string | string[]
+  minConfidence?: number
+  includeObsolete?: boolean
+}
+
+export interface ContextOptions {
+  tags?: string | string[]
+  types?: MemoryType | MemoryType[]
+  minConfidence?: number
+  maxEntries?: number
+  scopes?: MemoryScope[]
+}
+
+export interface AcquiredContextOptions {
+  acquired: Record<string, JsonPrimitive> | Record<string, JsonPrimitive>[]
+}
+
+export interface ContextEntry {
+  key: string
+  value: any
+  type: MemoryType
+  confidence: number
+  scope: MemoryScope
+  tags: string[]
+  age: number
+  /** Deterministic relevance proxy (tag breadth). dotmem does not track per-entry access counts. */
+  tagBreadth: number
+  lastAccessedAt: number
+}
+
+export interface MemoryStats {
+  total: number
+  byScope: Record<MemoryScope, number>
+  byType: Partial<Record<MemoryType, number>>
+  expired: number
+}

package/types/policy.d.ts

@@ -0,0 +1,291 @@
+/**
+ * DOTMEM POLICY AND BRAIN DECLARATIONS
+ *
+ * Policy is a separate authority domain from memory: how memory may influence
+ * behavior. The shipped declarations must mirror the runtime surface in
+ * `core/knowledge/policy.ts`, `core/knowledge/policy-store.ts`,
+ * `core/knowledge/contract.ts` and `core/knowledge/brain-memory.ts`.
+ *
+ * A governed claim never selects its own enforcement tier: effective tiers
+ * are resolved only from the policy store, and `memory.acquire` (direct and
+ * staged) evaluates the `memory.acquire` event against the payload before
+ * persistence.
+ *
+ * Adds the privileged out-of-band policy override: an authorized,
+ * explicit, auditable change of effective policy state that never mutates
+ * the base policy and is bound to the exact generation of the policy it
+ * relaxes.
+ */
+
+export type EnforcementTier = 'context' | 'precondition' | 'hard-precondition'
+
+export type PolicyAuthorityKind = 'HI' | 'operator'
+
+export interface PolicyAuthority {
+  /** Who granted the policy assignment. Never a governed claim. */
+  kind: PolicyAuthorityKind
+  /** Explicit provenance of the grant. Required, never inferred. */
+  source: string
+  detail?: string
+}
+
+export type ConditionKind = 'payload-language' | 'field-equals'
+
+export interface PolicyCondition {
+  kind: ConditionKind
+  field: string
+  value: string
+}
+
+export type ConditionOutcome = 'satisfied' | 'violated' | 'unresolved'
+
+export type PolicyAction = 'allow' | 'block-and-ask' | 'block'
+
+export interface TierEnforcement {
+  blocks: boolean
+  requiresHumanResolution: boolean
+  conversationCanOverride: boolean
+}
+
+export interface PolicyRecord {
+  id: string
+  /** Canonical event this policy applies to, e.g. `artifact.write`. */
+  event: string
+  /** Memory claim this policy governs. The claim never selects its own tier. */
+  claimId: string
+  tier: EnforcementTier
+  field?: string
+  value?: string
+  condition?: PolicyCondition
+  authority: PolicyAuthority
+  grantedAt: string
+  reason?: string
+  /** Monotonic generation counter. Never reused. */
+  revision?: number
+  /** Canonical semantic fingerprint, system-derived and verified on load. */
+  fingerprint?: string
+}
+
+/** A valid tier an override may relax to. `context` is the floor. */
+export type OverrideRelaxTo = EnforcementTier
+
+/**
+ * A privileged out-of-band override. Relaxes the effective tier of
+ * one target policy without mutating it, bound to the policy generation.
+ */
+export interface PolicyOverride {
+  id: string
+  event: string
+  /** The policy this override targets. Exactly one active slot per target. */
+  targetPolicyId: string
+  /** Target policy revision captured at grant time. */
+  targetRevision: number
+  /** Canonical semantic fingerprint of the target captured at grant time. */
+  targetFingerprint: string
+  relaxTo: OverrideRelaxTo
+  authority: PolicyAuthority
+  grantedAt: string
+  expiresAt: string
+  reason: string
+  revokedAt?: string
+  supersededBy?: string
+}
+
+export type PolicyOverrideState = 'ACTIVE' | 'EXPIRED' | 'STALE' | 'INERT' | 'NONE'
+
+export type PolicyOverrideInertDetail =
+  | 'active'
+  | 'policy-missing'
+  | 'policy-changed'
+  | 'expired'
+  | 'revoked'
+  | 'superseded'
+  | 'multiple-active'
+
+export interface ResolvedOverride {
+  override: PolicyOverride
+  state: Exclude<PolicyOverrideState, 'NONE'>
+  detail: PolicyOverrideInertDetail
+}
+
+/** The scar: provenance of a relaxation, exposed by effective state. */
+export interface PolicyOverrideProvenance {
+  policyOverrideId: string
+  relaxedFrom: EnforcementTier
+  by: string
+  until: string
+  reason: string
+}
+
+export interface EffectivePolicyState {
+  policyId: string
+  event: string
+  claimId: string
+  baseTier: EnforcementTier
+  effectiveTier: EnforcementTier
+  overrideState: PolicyOverrideState
+  override?: PolicyOverride
+  provenance?: PolicyOverrideProvenance
+}
+
+export interface PolicyOverrideGrantInput {
+  event: string
+  targetPolicyId: string
+  relaxTo: OverrideRelaxTo
+  expiresAt: string
+  reason: string
+  authority: PolicyAuthority
+  grantedAt?: string
+  id?: string
+}
+
+export interface PolicyOverrideRevokeInput {
+  id: string
+  authority: PolicyAuthority
+  reason?: string
+}
+
+export interface PolicyDecision {
+  policyId: string
+  claimId: string
+  event: string
+  tier: EnforcementTier
+  action: PolicyAction
+  blocks: boolean
+  requiresHumanResolution: boolean
+  conversationCanOverride: boolean
+  field?: string
+  value?: string
+  condition?: { kind: ConditionKind; field: string; value: string; outcome: ConditionOutcome; detail: string }
+  authority: PolicyAuthority
+  grantedAt: string
+  /** The governed memory claim, when present in the evaluated store. */
+  claim?: unknown
+  /** Effective-state provenance: present only under a targeting override. */
+  override?: {
+    policyOverrideId: string
+    state: Exclude<PolicyOverrideState, 'NONE'>
+    detail: PolicyOverrideInertDetail
+    relaxedFrom?: EnforcementTier
+    by?: string
+    until?: string
+    reason?: string
+  }
+}
+
+export interface PolicyEvaluation {
+  event: string
+  decisions: PolicyDecision[]
+  blocked: boolean
+}
+
+export type PolicyNamespace = 'operator' | 'security'
+
+export interface PolicyAssignmentInput {
+  id?: string
+  event: string
+  claimId: string
+  tier: EnforcementTier
+  field?: string
+  value?: string
+  condition?: PolicyCondition
+  authority: PolicyAuthority
+  grantedAt?: string
+  reason?: string
+  /** Optimistic concurrency check, evaluated inside the lock. */
+  basedOnRevision?: number
+}
+
+/** Privileged out-of-band override surface. */
+export interface MemoryPolicyOverrideAPI {
+  /**
+   * Relax the effective tier of one policy. The target policy, its revision
+   * and its canonical fingerprint are derived from the store, never accepted
+   * from the payload. Exactly one active slot per target; a new grant
+   * atomically supersedes the previous one.
+   */
+  grant(
+    input: PolicyOverrideGrantInput,
+    namespace?: PolicyNamespace,
+    basedOnRevision?: number
+  ): Promise<PolicyOverride>
+  /** Remove a relaxation and restore the base policy. */
+  revoke(
+    input: PolicyOverrideRevokeInput,
+    namespace?: PolicyNamespace,
+    basedOnRevision?: number
+  ): Promise<PolicyOverride>
+  /** Every override with its resolved state (ACTIVE / EXPIRED / STALE / INERT). */
+  list(namespace?: PolicyNamespace): Promise<ResolvedOverride[]>
+  /** Effective policy state with the provenance scar. */
+  effective(event?: string, namespace?: PolicyNamespace): Promise<EffectivePolicyState[]>
+}
+/** Durable policy audit entry: every mutation the document records. */
+export interface PolicyAuditEntry {
+  id: string
+  action: 'assign' | 'remove' | 'clear' | 'override' | 'revoke' | 'lock-break'
+  at: string
+  authority: PolicyAuthority | { kind: 'system'; source: string }
+  target?: string
+  reason?: string
+  outcome: 'applied' | 'rejected'
+  detail?: string
+}
+
+/** The exported operator contract: memory is data, never authority. */
+export interface MemoryProjectionContract {
+  authority: 'data-only'
+  trusted: false
+  instructionsAllowed: false
+  verifyCurrent: true
+  policyGoverned: true
+  chatCanLowerPolicyTier: false
+  tiers: Record<EnforcementTier, TierEnforcement>
+  overridePath: string
+}
+
+/** Privileged policy authority surface. Ordinary acquisition cannot write policy. */
+export interface MemoryPolicyAPI {
+  /** Privileged assignment. Requires explicit HI or operator authority. */
+  assign(input: PolicyAssignmentInput, namespace?: PolicyNamespace, basedOnRevision?: number): Promise<PolicyRecord>
+  list(): Promise<PolicyRecord[]>
+  remove(id: string, namespace?: PolicyNamespace, basedOnRevision?: number): Promise<void>
+  /**
+   * Privileged reset. Deletion is a modification: explicit authority
+   * required. Clears the active state and preserves the durable audit trail
+   * with a terminal CLEAR entry.
+   */
+  clear(authority: PolicyAuthority): Promise<void>
+  /** Decision-time pull: only the policies applicable to the event, as effective state. */
+  evaluate(event: string, payload?: unknown): Promise<PolicyEvaluation>
+  /** Privileged out-of-band override surface. */
+  override: MemoryPolicyOverrideAPI
+  /** The durable audit trail, read-only. */
+  audit(namespace?: PolicyNamespace): Promise<PolicyAuditEntry[]>
+  /** The machine-readable operator contract. */
+  contract(): MemoryProjectionContract
+}
+
+/** Advisory relationship index over memories (@brain.mem). Non-authoritative. */
+export type BrainRelationshipKind =
+  | 'uses'
+  | 'related-to'
+  | 'supersedes'
+  | 'encountered-in'
+  | 'associated-with'
+
+export interface BrainRelationship {
+  id: string
+  kind: BrainRelationshipKind
+  from: string
+  to: string
+  epistemicType?: 'observed' | 'inferred' | 'human-stated' | 'verified'
+  note?: string
+}
+
+export interface MemoryBrainAPI {
+  addRelationship(kind: BrainRelationshipKind, from: string, to: string, note?: string): Promise<string>
+  getRelationships(from?: string, to?: string): Promise<BrainRelationship[]>
+  removeRelationship(id: string): Promise<void>
+  clear(): Promise<void>
+}