@ldclabs/kip-lang 2.0.2 → 2.2.0

package/src/exec-ast.ts

@@ -172,7 +172,8 @@ export interface KqlQuery {
   cursor: Scalar | null
 }
 
-export type AsOf = { Seq: Scalar } | { Tx: Scalar } | { Time: Scalar }
+/** Cognitive time is a sequence coordinate; ids and instants resolve to one first. */
+export type AsOf = { Seq: Scalar }
 
 export interface FindClause {
   expressions: FindExpression[]
@@ -306,16 +307,27 @@ export type MutationClause =
   | { CreateAssertion: RecordCreate }
   | { CreateActivity: RecordCreate }
   | { Update: UpdateStatement }
-  | { RetractAssertion: RetractAssertion }
-  | { SupersedeAssertion: SupersedeAssertion }
-  | { CorrectEvidence: CorrectEvidence }
-  | { TransitionActivity: TransitionActivity }
+  | { Transition: Transition }
   | { SetRetention: SetRetention }
-  | { Archive: RemovalStatement }
-  | { Tombstone: RemovalStatement }
   | { Purge: PurgeStatement }
+  | { PurgePayload: PurgePayloadStatement }
   | { MergeConcept: MergeConcept }
 
+/**
+ * `EXPECT VERSION n [OF plane]` (Spec §35.1). Without a plane the guard is
+ * on the element's `_system.version`; with one, on that plane's own version.
+ */
+export interface ExpectVersion {
+  version: Scalar
+  plane: VersionPlane | null
+}
+
+export type VersionPlane =
+  | 'Attributes'
+  | 'Structural'
+  | 'Retention'
+  | { Facet: SymbolRef }
+
 export interface ConceptCreate {
   handle: string
   type: SymbolRef | null
@@ -330,7 +342,7 @@ export interface ConceptCreate {
 export interface ConceptUpsert {
   handle: string
   match: ObjectMatcher | null
-  expect_version: Scalar | null
+  expect_versions: ExpectVersion[]
   set_fields: Assignments | null
   set_attributes: Assignments | null
   set_facets: FacetAssignment[]
@@ -354,7 +366,7 @@ export interface EnsureProposition {
   subject: Term
   predicate: PredAtom
   object: Term
-  expect_version: Scalar | null
+  expect_versions: ExpectVersion[]
 }
 
 export interface FacetAssignment {
@@ -405,14 +417,14 @@ export type UpdateFunction = 'Add' | 'Mul' | 'Clamp' | 'Coalesce'
 
 export interface UpdateStatement {
   target: ElementRef
-  expect_version: Scalar | null
   actions: UpdateAction[]
   /**
    * `null` when the statement names its target directly and omits WHERE —
-   * the same shape as the removal family (Spec §58).
+   * the same shape as TRANSITION and the removal family (Spec §58).
    */
   where_clauses: WhereClause[] | null
   limit: Scalar | null
+  expect_versions: ExpectVersion[]
 }
 
 export type UpdateAction =
@@ -424,31 +436,21 @@ export type UpdateAction =
   | { SetStructural: StructuralEdge[] }
   | { UnsetStructural: StructuralRemoval[] }
 
-export interface RetractAssertion {
-  target: ElementRef
-  where_clauses: WhereClause[] | null
-  limit: Scalar | null
-  expect_state: Scalar | null
-}
-
-export interface SupersedeAssertion {
-  target: ElementRef
-  by: ElementRef
-  expect_state: Scalar | null
-}
-
-export interface CorrectEvidence {
-  target: ElementRef
-  by: ElementRef
-  expect_state: Scalar | null
-}
-
-export interface TransitionActivity {
+/**
+ * The one lifecycle statement (Spec §52.5): `to` names the move, the engine
+ * validates it against the target's kind and current state. `by` carries the
+ * replacing element for `superseded` / `corrected`; `set_fields` and
+ * `set_structural` finalize a pending Activity in the same transition.
+ */
+export interface Transition {
   target: ElementRef
   to: Scalar
+  by: ElementRef | null
   set_fields: Assignments | null
   set_structural: StructuralEdge[] | null
-  expect_state: Scalar | null
+  where_clauses: WhereClause[] | null
+  limit: Scalar | null
+  expect_versions: ExpectVersion[]
 }
 
 export interface SetRetention {
@@ -456,21 +458,28 @@ export interface SetRetention {
   values: Assignments
   where_clauses: WhereClause[] | null
   limit: Scalar | null
-  expect_version: Scalar | null
+  expect_versions: ExpectVersion[]
 }
 
-export interface RemovalStatement {
+export interface PurgeStatement {
   target: ElementRef
   where_clauses: WhereClause[] | null
   limit: Scalar | null
-  expect_state: Scalar | null
+  expect_versions: ExpectVersion[]
+  reference_policy: Scalar | null
+  /** Always the literal `PURGE`; the grammar freezes the spelling. */
+  confirm: string
 }
 
-export interface PurgeStatement {
+/**
+ * Payload-only purge (Spec §60.6): Evidence bytes are destroyed, the element
+ * survives, so no reference policy exists.
+ */
+export interface PurgePayloadStatement {
   target: ElementRef
   where_clauses: WhereClause[] | null
   limit: Scalar | null
-  reference_policy: Scalar | null
+  expect_versions: ExpectVersion[]
   /** Always the literal `PURGE`; the grammar freezes the spelling. */
   confirm: string
 }
@@ -479,7 +488,7 @@ export interface MergeConcept {
   source: ElementRef
   into: ElementRef
   where_clauses: WhereClause[] | null
-  expect_version: Scalar | null
+  expect_versions: ExpectVersion[]
 }
 
 // ---------------------------------------------------------------------------
@@ -495,13 +504,11 @@ export type MetaCommand =
   | { Preview: PreviewCommand }
   | { History: HistoryCommand }
   | { Changes: ChangesCommand }
-  | { Snapshot: { as_of: AsOf | null } }
   | { ExportCapsule: ExportCapsuleCommand }
 
 export type DescribeTarget =
   | { Primer: { mode: Scalar | null } }
   | 'Protocol'
-  | 'ExecutionContext'
   | 'Capabilities'
   | { Space: { value: Scalar | null } }
   | { SchemaEnvironment: { as_of: AsOf | null } }
@@ -514,10 +521,9 @@ export type DescribeTarget =
   | { Error: Scalar }
   | { Transaction: Scalar }
   | { TransactionByIdempotencyKey: Scalar }
-  | { Snapshot: { as_of: AsOf | null } }
+  | { Snapshot: { as_of: AsOf | null; at_time: Scalar | null } }
   | { Capsule: Scalar }
   | { EpistemicPolicy: { value: Scalar | null } }
-  | 'ProjectionCapability'
   | { Trust: { value: Scalar | null } }
   | { Access: { with: Record<string, BoundValue> | null } }
 
@@ -525,6 +531,10 @@ export interface ListCommand {
   target: ListTarget
   /** `LIST SCHEMA PACKAGES STATUS ...` only. */
   status: Scalar | null
+  /** `LIST DEPENDENTS :id` only — the traversal root. */
+  element: Scalar | null
+  /** `LIST DEPENDENTS ... DEPTH :n` only. */
+  depth: Scalar | null
   limit: Scalar | null
   cursor: Scalar | null
 }
@@ -537,6 +547,7 @@ export type ListTarget =
   | 'Facets'
   | 'StructuralFields'
   | 'EpistemicPolicies'
+  | 'Dependents'
 
 export interface SearchCommand {
   target: SearchTarget

package/src/formatter.ts

@@ -34,14 +34,11 @@ import type {
   UnsetFacetClause,
   UpdateStatement,
   UpdateAction,
-  RetractAssertionStatement,
-  SupersedeAssertionStatement,
-  CorrectEvidenceStatement,
-  TransitionActivityStatement,
+  ExpectVersionClause,
+  TransitionStatement,
   SetRetentionStatement,
-  ArchiveStatement,
-  TombstoneStatement,
   PurgeStatement,
+  PurgePayloadStatement,
   MergeConceptStatement,
   DescribeStatement,
   ListStatement,
@@ -51,7 +48,6 @@ import type {
   PreviewStatement,
   HistoryStatement,
   ChangesStatement,
-  SnapshotStatement,
   ExportCapsuleStatement,
   Expression,
   ScalarValue,
@@ -197,9 +193,6 @@ class Formatter {
       case 'ChangesStatement':
         this.formatChanges(stmt)
         break
-      case 'SnapshotStatement':
-        this.formatSnapshot(stmt)
-        break
       case 'ExportCapsuleStatement':
         this.formatExport(stmt)
         break
@@ -234,30 +227,18 @@ class Formatter {
       case 'UpdateStatement':
         this.formatUpdate(stmt)
         break
-      case 'RetractAssertionStatement':
-        this.formatRetract(stmt)
-        break
-      case 'SupersedeAssertionStatement':
-        this.formatSupersede(stmt)
-        break
-      case 'CorrectEvidenceStatement':
-        this.formatCorrect(stmt)
-        break
-      case 'TransitionActivityStatement':
+      case 'TransitionStatement':
         this.formatTransition(stmt)
         break
       case 'SetRetentionStatement':
         this.formatSetRetention(stmt)
         break
-      case 'ArchiveStatement':
-        this.formatRemoval('ARCHIVE', stmt)
-        break
-      case 'TombstoneStatement':
-        this.formatRemoval('TOMBSTONE', stmt)
-        break
       case 'PurgeStatement':
         this.formatPurge(stmt)
         break
+      case 'PurgePayloadStatement':
+        this.formatPurgePayload(stmt)
+        break
       case 'MergeConceptStatement':
         this.formatMerge(stmt)
         break
@@ -325,7 +306,28 @@ class Formatter {
   }
 
   private asOfToString(clause: AsOfClause): string {
-    return `AS OF ${clause.basis} ${this.scalar(clause.value)}`
+    return `AS OF SEQ ${this.scalar(clause.value)}`
+  }
+
+  private expectVersionToString(clause: ExpectVersionClause): string {
+    let text = `EXPECT VERSION ${this.scalar(clause.value)}`
+    if (clause.plane) {
+      text +=
+        clause.plane.kind === 'FACET'
+          ? ` OF FACET ${this.symbol(clause.plane.facet)}`
+          : ` OF ${clause.plane.kind}`
+    }
+    return text
+  }
+
+  /** Trailing guards, one per line at the statement's own indentation. */
+  private formatExpectVersions(clauses: ExpectVersionClause[]): void {
+    for (const clause of clauses) {
+      this.emitCommentsBefore(clause.range.start.line)
+      this.writeIndent()
+      this.write(this.expectVersionToString(clause))
+      this.newline()
+    }
   }
 
   // ────────────────────────────────────────────────────────────────────
@@ -598,17 +600,6 @@ class Formatter {
         }
       })
     }
-    if (stmt.expectVersion) {
-      const node = stmt.expectVersion
-      clauses.push({
-        node,
-        print: () => {
-          this.writeIndent()
-          this.write(`EXPECT VERSION ${this.scalar(node.value)}`)
-          this.newline()
-        }
-      })
-    }
     if (stmt.setFields) {
       const node = stmt.setFields
       clauses.push({
@@ -651,6 +642,7 @@ class Formatter {
       stmt.range.end.line,
       clauses
     )
+    this.formatExpectVersions(stmt.expectVersions)
   }
 
   private formatRecordCreate(
@@ -698,8 +690,8 @@ class Formatter {
     this.write('ENSURE PROPOSITION ')
     if (stmt.handle) this.write(`${stmt.handle.name} `)
     this.write(this.tupleToString(stmt.tuple))
-    if (stmt.expectVersion) {
-      this.write(` EXPECT VERSION ${this.scalar(stmt.expectVersion.value)}`)
+    for (const clause of stmt.expectVersions) {
+      this.write(` ${this.expectVersionToString(clause)}`)
     }
     this.newline()
   }
@@ -726,12 +718,6 @@ class Formatter {
     this.write(`UPDATE ${this.targetRef(stmt.target)}`)
     this.newline()
 
-    if (stmt.expectVersion) {
-      this.emitCommentsBefore(stmt.expectVersion.range.start.line)
-      this.writeIndent()
-      this.write(`EXPECT VERSION ${this.scalar(stmt.expectVersion.value)}`)
-      this.newline()
-    }
     for (const action of stmt.actions) {
       this.emitCommentsBefore(action.range.start.line)
       this.formatUpdateAction(action)
@@ -744,6 +730,7 @@ class Formatter {
       this.emitCommentsBefore(stmt.limit.range.start.line)
       this.formatLimit(stmt.limit)
     }
+    this.formatExpectVersions(stmt.expectVersions)
   }
 
   private formatUpdateAction(action: UpdateAction): void {
@@ -776,52 +763,13 @@ class Formatter {
     }
   }
 
-  private formatRetract(stmt: RetractAssertionStatement): void {
-    this.writeIndent()
-    this.write(`RETRACT ASSERTION ${this.targetRef(stmt.target)}`)
-    if (!stmt.where && !stmt.limit && stmt.expectState) {
-      this.write(` EXPECT STATE ${this.scalar(stmt.expectState.value)}`)
-      this.newline()
-      return
-    }
-    this.newline()
-    if (stmt.where) this.formatWhere(stmt.where, 'WHERE')
-    if (stmt.limit) this.formatLimit(stmt.limit)
-    if (stmt.expectState) {
-      this.writeIndent()
-      this.write(`EXPECT STATE ${this.scalar(stmt.expectState.value)}`)
-      this.newline()
-    }
-  }
-
-  private formatSupersede(stmt: SupersedeAssertionStatement): void {
+  private formatTransition(stmt: TransitionStatement): void {
     this.writeIndent()
-    this.write(
-      `SUPERSEDE ASSERTION ${this.targetRef(stmt.target)} BY ${this.targetRef(stmt.by)}`
-    )
-    if (stmt.expectState) {
-      this.write(` EXPECT STATE ${this.scalar(stmt.expectState.value)}`)
-    }
-    this.newline()
-  }
-
-  private formatCorrect(stmt: CorrectEvidenceStatement): void {
-    this.writeIndent()
-    this.write(
-      `CORRECT EVIDENCE ${this.targetRef(stmt.target)} BY ${this.targetRef(stmt.by)}`
-    )
-    if (stmt.expectState) {
-      this.write(` EXPECT STATE ${this.scalar(stmt.expectState.value)}`)
-    }
-    this.newline()
-  }
-
-  private formatTransition(stmt: TransitionActivityStatement): void {
-    this.writeIndent()
-    this.write(
-      `TRANSITION ACTIVITY ${this.targetRef(stmt.target)} TO ${this.scalar(stmt.to)}`
-    )
+    this.write(`TRANSITION ${this.targetRef(stmt.target)} TO ${this.scalar(stmt.to)}`)
+    if (stmt.by) this.write(` BY ${this.targetRef(stmt.by)}`)
+    const tail = stmt.finalize.length > 0 || stmt.where || stmt.limit || stmt.expectVersions.length > 0
     this.newline()
+    if (!tail) return
     if (stmt.finalize.length > 0) {
       this.indentLevel++
       for (const clause of stmt.finalize) {
@@ -834,14 +782,9 @@ class Formatter {
       }
       this.indentLevel--
     }
-    if (stmt.expectState) {
-      this.indentLevel++
-      this.emitCommentsBefore(stmt.expectState.range.start.line)
-      this.writeIndent()
-      this.write(`EXPECT STATE ${this.scalar(stmt.expectState.value)}`)
-      this.newline()
-      this.indentLevel--
-    }
+    if (stmt.where) this.formatWhere(stmt.where, 'WHERE')
+    if (stmt.limit) this.formatLimit(stmt.limit)
+    this.formatExpectVersions(stmt.expectVersions)
   }
 
   private formatSetRetention(stmt: SetRetentionStatement): void {
@@ -851,48 +794,36 @@ class Formatter {
     this.newline()
     if (stmt.where) this.formatWhere(stmt.where, 'WHERE')
     if (stmt.limit) this.formatLimit(stmt.limit)
-    if (stmt.expectVersion) {
-      this.writeIndent()
-      this.write(`EXPECT VERSION ${this.scalar(stmt.expectVersion.value)}`)
-      this.newline()
-    }
+    this.formatExpectVersions(stmt.expectVersions)
   }
 
-  private formatRemoval(
-    keyword: string,
-    stmt: ArchiveStatement | TombstoneStatement
-  ): void {
+  private formatPurge(stmt: PurgeStatement): void {
     this.writeIndent()
-    this.write(`${keyword} ${this.targetRef(stmt.target)}`)
-    if (!stmt.where && !stmt.limit) {
-      if (stmt.expectState) {
-        this.write(` EXPECT STATE ${this.scalar(stmt.expectState.value)}`)
-      }
-      this.newline()
-      return
-    }
+    this.write(`PURGE ${this.targetRef(stmt.target)}`)
     this.newline()
     if (stmt.where) this.formatWhere(stmt.where, 'WHERE')
     if (stmt.limit) this.formatLimit(stmt.limit)
-    if (stmt.expectState) {
+    this.formatExpectVersions(stmt.expectVersions)
+    this.indentLevel++
+    if (stmt.referencePolicy) {
       this.writeIndent()
-      this.write(`EXPECT STATE ${this.scalar(stmt.expectState.value)}`)
+      this.write(`REFERENCE POLICY ${this.scalar(stmt.referencePolicy)}`)
       this.newline()
     }
+    this.writeIndent()
+    this.write(`CONFIRM ${stmt.confirm.value}`)
+    this.newline()
+    this.indentLevel--
   }
 
-  private formatPurge(stmt: PurgeStatement): void {
+  private formatPurgePayload(stmt: PurgePayloadStatement): void {
     this.writeIndent()
-    this.write(`PURGE ${this.targetRef(stmt.target)}`)
+    this.write(`PURGE PAYLOAD ${this.targetRef(stmt.target)}`)
     this.newline()
     if (stmt.where) this.formatWhere(stmt.where, 'WHERE')
     if (stmt.limit) this.formatLimit(stmt.limit)
+    this.formatExpectVersions(stmt.expectVersions)
     this.indentLevel++
-    if (stmt.referencePolicy) {
-      this.writeIndent()
-      this.write(`REFERENCE POLICY ${this.scalar(stmt.referencePolicy)}`)
-      this.newline()
-    }
     this.writeIndent()
     this.write(`CONFIRM ${stmt.confirm.value}`)
     this.newline()
@@ -906,11 +837,7 @@ class Formatter {
     )
     this.newline()
     if (stmt.where) this.formatWhere(stmt.where, 'WHERE')
-    if (stmt.expectVersion) {
-      this.writeIndent()
-      this.write(`EXPECT VERSION ${this.scalar(stmt.expectVersion.value)}`)
-      this.newline()
-    }
+    this.formatExpectVersions(stmt.expectVersions)
   }
 
   // ────────────────────────────────────────────────────────────────────
@@ -1001,7 +928,6 @@ class Formatter {
     const words: Record<DescribeStatement['target'], string> = {
       PRIMER: 'PRIMER',
       PROTOCOL: 'PROTOCOL',
-      EXECUTION_CONTEXT: 'EXECUTION CONTEXT',
       CAPABILITIES: 'CAPABILITIES',
       SPACE: 'SPACE',
       SCHEMA_ENVIRONMENT: 'SCHEMA ENVIRONMENT',
@@ -1017,7 +943,6 @@ class Formatter {
       SNAPSHOT: 'SNAPSHOT',
       CAPSULE: 'CAPSULE',
       EPISTEMIC_POLICY: 'EPISTEMIC POLICY',
-      PROJECTION_CAPABILITY: 'PROJECTION CAPABILITY',
       TRUST: 'TRUST',
       ACCESS: 'ACCESS'
     }
@@ -1030,6 +955,7 @@ class Formatter {
     }
     if (stmt.mode) this.write(` MODE ${this.scalar(stmt.mode)}`)
     if (stmt.asOf) this.write(` ${this.asOfToString(stmt.asOf)}`)
+    if (stmt.atTime) this.write(` AT TIME ${this.scalar(stmt.atTime)}`)
     if (stmt.with) this.write(` WITH ${this.objectLiteralToString(stmt.with)}`)
     this.newline()
   }
@@ -1043,9 +969,12 @@ class Formatter {
       PREDICATES: 'PREDICATES',
       FACETS: 'FACETS',
       STRUCTURAL_FIELDS: 'STRUCTURAL FIELDS',
-      EPISTEMIC_POLICIES: 'EPISTEMIC POLICIES'
+      EPISTEMIC_POLICIES: 'EPISTEMIC POLICIES',
+      DEPENDENTS: 'DEPENDENTS'
     }
     this.write(`LIST ${words[stmt.target]}`)
+    if (stmt.element) this.write(` ${this.scalar(stmt.element)}`)
+    if (stmt.depth) this.write(` DEPTH ${this.scalar(stmt.depth)}`)
     if (stmt.status) this.write(` STATUS ${this.scalar(stmt.status)}`)
     if (stmt.limit) this.write(` LIMIT ${this.scalar(stmt.limit.value)}`)
     if (stmt.cursor) this.write(` CURSOR ${this.scalar(stmt.cursor.value)}`)
@@ -1127,13 +1056,6 @@ class Formatter {
     this.newline()
   }
 
-  private formatSnapshot(stmt: SnapshotStatement): void {
-    this.writeIndent()
-    this.write('SNAPSHOT')
-    if (stmt.asOf) this.write(` ${this.asOfToString(stmt.asOf)}`)
-    this.newline()
-  }
-
   private formatExport(stmt: ExportCapsuleStatement): void {
     this.writeIndent()
     this.write(`EXPORT CAPSULE ${this.targetRef(stmt.target)}`)

package/src/index.ts

@@ -88,17 +88,13 @@ export type {
   UnsetStructuralClause,
   StructuralRemoval,
   ExpectVersionClause,
-  ExpectStateClause,
+  VersionPlane,
   UpdateStatement,
   UpdateAction,
-  RetractAssertionStatement,
-  SupersedeAssertionStatement,
-  CorrectEvidenceStatement,
-  TransitionActivityStatement,
+  TransitionStatement,
   SetRetentionStatement,
-  ArchiveStatement,
-  TombstoneStatement,
   PurgeStatement,
+  PurgePayloadStatement,
   MergeConceptStatement,
   // META
   DescribeStatement,
@@ -114,7 +110,6 @@ export type {
   PreviewStatement,
   HistoryStatement,
   ChangesStatement,
-  SnapshotStatement,
   ExportCapsuleStatement,
   // Expressions
   Expression,
@@ -199,13 +194,12 @@ export type {
   UpdateFunction,
   UpdateStatement as ExecUpdateStatement,
   UpdateAction as ExecUpdateAction,
-  RetractAssertion,
-  SupersedeAssertion,
-  CorrectEvidence,
-  TransitionActivity,
+  ExpectVersion,
+  VersionPlane as ExecVersionPlane,
+  Transition,
   SetRetention,
-  RemovalStatement,
   PurgeStatement as ExecPurgeStatement,
+  PurgePayloadStatement as ExecPurgePayloadStatement,
   MergeConcept,
   // META
   MetaCommand,