@ldclabs/kip-lang 2.0.1 → 2.1.0

package/src/parser.ts

@@ -74,6 +74,7 @@ import type {
   ArchiveStatement,
   TombstoneStatement,
   PurgeStatement,
+  PurgePayloadStatement,
   MergeConceptStatement,
   DescribeStatement,
   DescribeTargetKind,
@@ -1907,10 +1908,13 @@ class Parser {
     }
   }
 
-  private parsePurgeStatement(): PurgeStatement {
+  private parsePurgeStatement(): PurgeStatement | PurgePayloadStatement {
     const leadingComments = this.collectLeadingComments()
     const start = this.currentPos()
-    this.expectKeywordWithSpace(TokenType.Purge)
+    const purge = this.expectKeywordWithSpace(TokenType.Purge)
+    if (this.check(TokenType.Payload)) {
+      return this.parsePurgePayloadTail(start, purge, leadingComments)
+    }
     const target = this.parseTargetRef()
 
     let where: WhereClause | undefined
@@ -1954,6 +1958,49 @@ class Parser {
     }
   }
 
+  /**
+   * `PURGE PAYLOAD` erases Evidence bytes while the element survives
+   * (Spec §60.6), so there is no REFERENCE POLICY clause; the confirmation
+   * literal is the same as element purge.
+   */
+  private parsePurgePayloadTail(
+    start: Position,
+    purge: Token,
+    leadingComments: string[]
+  ): PurgePayloadStatement {
+    this.expectSecondWord(TokenType.Payload, purge)
+    const target = this.parseTargetRef()
+
+    let where: WhereClause | undefined
+    if (this.check(TokenType.Where)) {
+      this.expectKeywordWithSpace(TokenType.Where)
+      this.dialect = 'raw'
+      where = this.parseWhereClause()
+    }
+
+    const limit = this.check(TokenType.Limit) ? this.parseLimitClause() : undefined
+
+    this.expect(TokenType.Confirm)
+    const confirmTok = this.current()
+    const confirm = this.parseStringLiteral()
+    if (confirm.parsed !== 'PURGE') {
+      this.error(
+        `PURGE PAYLOAD must be confirmed with the exact literal "PURGE", got ${confirmTok.value}`,
+        confirmTok
+      )
+    }
+
+    return {
+      kind: 'PurgePayloadStatement',
+      target,
+      where,
+      limit,
+      confirm,
+      range: { start, end: this.endPos() },
+      leadingComments: leadingComments.length ? leadingComments : undefined
+    }
+  }
+
   private parseMergeConcept(): MergeConceptStatement {
     const leadingComments = this.collectLeadingComments()
     const start = this.currentPos()
@@ -2123,6 +2170,8 @@ class Parser {
 
     let target: ListTargetKind
     let status: ScalarValue | undefined
+    let element: ScalarValue | undefined
+    let depth: ScalarValue | undefined
 
     switch (tok.type) {
       case TokenType.Spaces:
@@ -2160,6 +2209,14 @@ class Parser {
         target = 'EPISTEMIC_POLICIES'
         break
       }
+      case TokenType.Dependents:
+        // Bounded reverse provenance closure (Spec §63.5): the operand is
+        // required, the DEPTH bound is optional and defaults engine-side to 1.
+        this.expectSecondWord(TokenType.Dependents, list)
+        target = 'DEPENDENTS'
+        element = this.parseScalarValue()
+        if (this.match(TokenType.Depth)) depth = this.parseScalarValue()
+        break
       default:
         this.error(`Unknown LIST target '${tok.value}'`, tok)
         throw new ParseAbort()
@@ -2174,6 +2231,8 @@ class Parser {
       kind: 'ListStatement',
       target,
       status,
+      element,
+      depth,
       limit,
       cursor,
       range: { start, end: this.endPos() },

package/src/semantics.ts

@@ -11,7 +11,8 @@ import type {
   ScalarValue,
   MutateStatement,
   AssertStatement,
-  SetFacetClause
+  SetFacetClause,
+  SetStructuralClause
 } from './ast.js'
 import type { Range } from './token.js'
 
@@ -54,6 +55,7 @@ const ASSERTION_STATES = new Set([
   'expired'
 ])
 const ACTIVITY_TERMINAL = new Set(['completed', 'failed', 'cancelled'])
+const EVIDENCE_ROLES = new Set(['support', 'challenge', 'context'])
 
 /** Signals the Profile fixes to `[0,1]`; none of them is truth. */
 const UNIT_INTERVAL_FIELDS = new Set([
@@ -96,11 +98,11 @@ function analyzeMutationClause(stmt: Statement, diags: Diagnostic[]): void {
       break
 
     case 'CreateConceptStatement':
-      for (const facet of stmt.setFacets) checkFacet(facet, diags)
-      break
-
     case 'UpsertConceptStatement':
+    case 'CreateEvidenceStatement':
+    case 'CreateActivityStatement':
       for (const facet of stmt.setFacets) checkFacet(facet, diags)
+      checkStructural(stmt.setStructural, diags)
       break
 
     case 'CreateAssertionStatement':
@@ -108,30 +110,62 @@ function analyzeMutationClause(stmt: Statement, diags: Diagnostic[]): void {
         checkAssignmentValues(stmt.setFields.assignments, diags)
       }
       for (const facet of stmt.setFacets) checkFacet(facet, diags)
-      break
-
-    case 'CreateEvidenceStatement':
-    case 'CreateActivityStatement':
-      for (const facet of stmt.setFacets) checkFacet(facet, diags)
+      checkStructural(stmt.setStructural, diags)
       break
 
     case 'UpdateStatement':
       for (const action of stmt.actions) {
         if (action.kind === 'SetFacetClause') checkFacet(action, diags)
+        // Core fields are Core-typed wherever they are written, so an UPDATE
+        // that sets one gets the same check `CREATE ASSERTION` already gets.
+        else if (action.kind === 'SetFieldsClause') {
+          checkAssignmentValues(action.assignments, diags)
+        } else if (action.kind === 'SetStructuralClause') {
+          checkStructural(action, diags)
+        }
       }
       if (stmt.where) checkWhere(stmt.where, !!stmt.limit, diags)
       break
 
+    // `EXPECT STATE` is checkable only where the target's kind is fixed by the
+    // statement itself. RETRACT and SUPERSEDE always name an Assertion, so the
+    // Assertion lifecycle registry applies. ARCHIVE and TOMBSTONE take any
+    // element — a Concept is not `retracted` and may well be `archived` — and
+    // Core registers no element-lifecycle vocabulary, so checking them here
+    // rejected commands the Specification admits.
     case 'RetractAssertionStatement':
-    case 'ArchiveStatement':
-    case 'TombstoneStatement':
+      if (stmt.expectState) {
+        checkEnum(stmt.expectState.value, ASSERTION_STATES, 'EXPECT STATE', diags)
+      }
+      if (stmt.where) checkWhere(stmt.where, !!stmt.limit, diags)
+      break
+
+    case 'SupersedeAssertionStatement':
       if (stmt.expectState) {
         checkEnum(stmt.expectState.value, ASSERTION_STATES, 'EXPECT STATE', diags)
       }
       break
 
+    case 'ArchiveStatement':
+    case 'TombstoneStatement':
+      if (stmt.where) checkWhere(stmt.where, !!stmt.limit, diags)
+      break
+
     case 'TransitionActivityStatement':
       checkEnum(stmt.to, ACTIVITY_TERMINAL, 'TRANSITION ACTIVITY TO', diags)
+      checkStructural(stmt.finalize.find(
+        (c): c is SetStructuralClause => c.kind === 'SetStructuralClause'
+      ), diags)
+      break
+
+    // Spec §52.7 names seven statements whose WHERE can select an unbounded
+    // set and which SHOULD therefore carry a LIMIT. Warning on the read and on
+    // UPDATE while staying silent on the removal ladder had it backwards: an
+    // over-broad PURGE is the one that cannot be undone.
+    case 'PurgeStatement':
+    case 'PurgePayloadStatement':
+    case 'SetRetentionStatement':
+      if (stmt.where) checkWhere(stmt.where, !!stmt.limit, diags)
       break
   }
 }
@@ -176,6 +210,26 @@ function checkFacet(clause: SetFacetClause, diags: Diagnostic[]): void {
   checkAssignmentValues(clause.assignments, diags)
 }
 
+/**
+ * `role` on an `("evidence", ...)` citation comes from the Core registry
+ * (Spec §20.13, §56.2), so a misspelling is as checkable here as a bad
+ * `stance`. Other structural fields carry engine- or package-defined options,
+ * which only the Schema Environment can judge.
+ */
+function checkStructural(
+  clause: SetStructuralClause | undefined,
+  diags: Diagnostic[]
+): void {
+  if (!clause) return
+  for (const edge of clause.assignments) {
+    if (edge.field.kind === 'ParameterRef' || edge.field.parsed !== 'evidence') {
+      continue
+    }
+    const role = edge.options?.entries.find((e) => e.key === 'role')
+    if (role) checkEnum(role.value, EVIDENCE_ROLES, 'Evidence role', diags)
+  }
+}
+
 function checkAssignmentValues(
   object: ObjectLiteral,
   diags: Diagnostic[]

package/src/token.ts

@@ -65,6 +65,7 @@ export enum TokenType {
   Archive = 'ARCHIVE',
   Tombstone = 'TOMBSTONE',
   Purge = 'PURGE',
+  Payload = 'PAYLOAD',
   Confirm = 'CONFIRM',
   Reference = 'REFERENCE',
   Policy = 'POLICY',
@@ -113,6 +114,8 @@ export enum TokenType {
   Facets = 'FACETS',
   Types = 'TYPES',
   Policies = 'POLICIES',
+  Dependents = 'DEPENDENTS',
+  Depth = 'DEPTH',
   Compatibility = 'COMPATIBILITY',
   From = 'FROM',
   Error = 'ERROR',
@@ -245,6 +248,7 @@ export const KEYWORDS: ReadonlyMap<string, TokenType> = new Map([
   ['ARCHIVE', TokenType.Archive],
   ['TOMBSTONE', TokenType.Tombstone],
   ['PURGE', TokenType.Purge],
+  ['PAYLOAD', TokenType.Payload],
   ['CONFIRM', TokenType.Confirm],
   ['REFERENCE', TokenType.Reference],
   ['POLICY', TokenType.Policy],
@@ -293,6 +297,8 @@ export const KEYWORDS: ReadonlyMap<string, TokenType> = new Map([
   ['FACETS', TokenType.Facets],
   ['TYPES', TokenType.Types],
   ['POLICIES', TokenType.Policies],
+  ['DEPENDENTS', TokenType.Dependents],
+  ['DEPTH', TokenType.Depth],
   ['COMPATIBILITY', TokenType.Compatibility],
   ['FROM', TokenType.From],
   ['ERROR', TokenType.Error],

package/src/version.ts

@@ -7,7 +7,7 @@
  * has to load in runtimes with no filesystem; `test/lower.test.mjs` asserts the
  * two stay in step.
  */
-export const PARSER_VERSION = '2.0.1'
+export const PARSER_VERSION = '2.1.0'
 
 /** The KIP specification revision this grammar targets. */
 export const KIP_SPEC_REVISION = '2.0-draft'