dsh-logicprobe 0.4.0 → 0.5.1

package/skills/logicprobe-datamodel/references/data-model-schema.md

@@ -0,0 +1,128 @@
+# DataModelV1 — logicprobe-datamodel Schema
+
+The `logicprobe_datamodel_verify` tool accepts a structured JSON data model. The engine runs DS/DA checks, and DD1-DD4 when `beforeModel` is supplied. It is host-agnostic; DSH uses the native tool, non-DSH hosts use `data-model-harness.py`.
+
+## Top-level model
+
+```json
+{
+  "schemaVersion": 1,
+  "entities": [
+    {
+      "name": "User",
+      "fields": [
+        { "name": "id", "type": "uuid", "required": true, "unique": true },
+        { "name": "email", "type": "string", "required": true, "unique": true }
+      ],
+      "primaryKey": ["id"]
+    }
+  ],
+  "relationships": [
+    { "fromEntity": "Order", "fromField": "userId", "toEntity": "User", "toField": "id", "onDelete": "restrict" }
+  ],
+  "invariants": [],
+  "boundaryChecks": []
+}
+```
+
+| Field | Required | Meaning |
+|---|---|---|
+| `schemaVersion` | yes | Must be `1` |
+| `entities` | yes | `{ name, fields, primaryKey?, uniqueKeys?, indexes? }` |
+| `relationships` | no | `{ fromEntity, fromField, toEntity, toField?, onDelete? }` |
+| `invariants` | no | See invariant kinds below |
+| `boundaryChecks` | no | `{ entity, field, values? }` for DA2 |
+
+## Field
+
+```json
+{
+  "name": "age",
+  "type": "integer",
+  "required": true,
+  "unique": false,
+  "nullable": false,
+  "default": 0,
+  "min": 0,
+  "max": 150,
+  "minLength": null,
+  "maxLength": null,
+  "pattern": null,
+  "enum": null,
+  "ref": null,
+  "items": null,
+  "monotonic": null
+}
+```
+
+Supported `type` values: `string`, `integer`, `number`, `boolean`, `uuid`, `date`, `datetime`, `timestamp`, `json`, `enum`, `array`, `object`, `binary`, or any custom non-empty type name.
+
+## Invariants
+
+| Kind | Shape | Checks |
+|---|---|---|
+| `field-required` | `{ entity, field }` | Field must be required |
+| `unique` | `{ entity, fields: [] }` | Unique constraint must exist |
+| `referential-integrity` | `{ entity, field, refEntity, refField? }` | Reference target must exist |
+| `range` | `{ entity, field, min?, max? }` | Range must be respected |
+| `count-equal` | `{ sourceEntity, targetEntity }` | Source/target counts must match |
+| `field-equal` | `{ sourceEntity, sourceField, targetEntity, targetField }` | Two fields must be equal |
+| `no-orphan` | `{ entity, field, refEntity }` | No dangling references |
+| `idempotent-copy` | `{ sourceEntity, targetEntity }` | A matching copy pair must exist; the copy is intended to be replay-safe |
+| `idempotent-migration` | `{ from, to }` | A matching migration mapping must exist; split/merge/drop are flagged as non-idempotent |
+| `monotonic` | `{ entity, field, direction: "inc"\|"dec" }` | Field must move only in the declared direction |
+| `sequence` | `{ steps: ["c1", "m1"] }` | Referenced copy/migration step ids must exist |
+| `leads-to` | `{ entity, field, from, to }` | For enum/status fields, both values must exist |
+| `atomicity` | `{ steps: ["c1", "m1"] }` | Steps must exist; non-atomic transforms and missing backups are flagged |
+
+## Tool arguments
+
+```json
+{
+  "model": { "...": "AFTER DataModelV1" },
+  "beforeModel": { "...": "BEFORE DataModelV1" },
+  "fieldMapping": { "User.name": "User.fullName" },
+  "copyPairs": [
+    { "id": "c1", "sourceEntity": "Source", "targetEntity": "Target", "mapping": { "a": "x" } }
+  ],
+  "migrationMappings": [
+    { "id": "m1", "from": "User.name", "to": "User.fullName", "transform": "rename" }
+  ],
+  "backupPairs": [
+    { "id": "b1", "sourceEntity": "Source", "targetEntity": "Target", "mapping": { "x": "a" } }
+  ]
+}
+```
+
+## Checks
+
+- **DS1-DS4**: schema well-formedness, required-field completeness, relationship integrity, type/nullability consistency
+- **DA1-DA12**: null/empty injection, boundary blast, uniqueness, referential integrity, migration coverage, copy consistency, rollback/backup symmetry, idempotent constraints, data monotonic, data sequence, data leads-to, data atomicity
+- **DD1-DD4**: data behavior preservation, data invariant continuity, delta summary, breaking-change regression
+
+## Minimal example
+
+```json
+{
+  "schemaVersion": 1,
+  "entities": [
+    {
+      "name": "User",
+      "fields": [
+        { "name": "id", "type": "uuid", "required": true },
+        { "name": "age", "type": "integer", "min": 0, "max": 150 }
+      ],
+      "primaryKey": ["id"]
+    }
+  ],
+  "boundaryChecks": [
+    { "entity": "User", "field": "age", "values": [-1, 0, 150, 151] }
+  ]
+}
+```
+
+## Limits
+
+- The engine is a design-time static verifier. It does not execute against a live database.
+- Data invariants like `count-equal` and `field-equal` are checked structurally (referenced entities/fields exist) unless sample data is provided in a future version.
+- Follow with runtime tools (Great Expectations, Soda, Pandera) for live data validation.

package/src/concurrency-tool.ts

@@ -0,0 +1,37 @@
+import { defineTool, type JsonValue } from '@deepseek-ai/dsh-tools'
+import { runConcurrencyScan } from './concurrency.js'
+
+export const LOGICPROBE_CONCURRENCY_SCAN_TOOL_NAME = 'logicprobe_concurrency_scan'
+
+/**
+ * Model-visible DSH tool that mines design documents/plans for concurrency-related
+ * claims and risk keywords. It does not prove concurrency safety; it flags terms
+ * such as "thread-safe", "lock-free", "race condition", "atomic", "mutex", etc.,
+ * so the model can either provide dedicated evidence or mark the claim unverified.
+ */
+export const logicProbeConcurrencyScanTool = defineTool({
+  name: LOGICPROBE_CONCURRENCY_SCAN_TOOL_NAME,
+  description:
+    'Scan a document or plan text for concurrency risk points. Use ONLY after confirming the target actually has concurrency requirements or behavior (threads, async tasks, interrupts, shared state, parallel execution). If the target is purely sequential, do not call this tool. Returns findings for keywords like thread-safe, lock-free, data race, race condition, atomic, synchronized, mutex, semaphore, shared variable, reentrant, interrupt-safe. Absolute claims (thread-safe, lock-free, no data race) are flagged as errors requiring dedicated verification.',
+  parameters: {
+    text: {
+      type: 'string',
+      required: true,
+      description: 'Document or plan text to scan for concurrency-related claims.',
+    },
+  },
+  output: {
+    schema: {
+      type: 'json',
+      description: 'Concurrency scan report with findings and summary.',
+    },
+    render(_args, value) {
+      return [{ type: 'text' as const, text: JSON.stringify(value, null, 2) }]
+    },
+  },
+  timeoutMs: 10_000,
+  isConcurrencySafe: () => true,
+  async execute(args) {
+    return runConcurrencyScan(args.text) as unknown as JsonValue
+  },
+})

package/src/concurrency.ts

@@ -0,0 +1,102 @@
+export interface ConcurrencyFinding {
+  code: 'CONCURRENCY_KEYWORD' | 'CONCURRENCY_ABSOLUTE_CLAIM'
+  severity: 'warning' | 'error'
+  message: string
+  line?: number
+  snippet?: string
+  keyword: string
+}
+
+export interface ConcurrencyScanReport {
+  ok: boolean
+  findings: ConcurrencyFinding[]
+  summary: {
+    lines: number
+    keywords: number
+    absoluteClaims: number
+    warnings: number
+    errors: number
+  }
+}
+
+interface KeywordRule {
+  pattern: RegExp
+  label: string
+  absolute: boolean
+}
+
+const KEYWORD_RULES: KeywordRule[] = [
+  { pattern: /\bthread\s*-?\s*safe\b/i, label: 'thread-safe', absolute: true },
+  { pattern: /\block\s*-?\s*free\b/i, label: 'lock-free', absolute: true },
+  { pattern: /\bwait\s*-?\s*free\b/i, label: 'wait-free', absolute: true },
+  { pattern: /\bno\s+data\s+race\b/i, label: 'no data race', absolute: true },
+  { pattern: /\brace\s*-?\s*free\b/i, label: 'race-free', absolute: true },
+  { pattern: /\bdata\s+race\b/i, label: 'data race', absolute: false },
+  { pattern: /\brace\s+condition\b/i, label: 'race condition', absolute: false },
+  { pattern: /\bthread\s*-?\s*safety\b/i, label: 'thread safety', absolute: false },
+  { pattern: /\bconcurrent\b/i, label: 'concurrent', absolute: false },
+  { pattern: /\bparallel\b/i, label: 'parallel', absolute: false },
+  { pattern: /\bmulti-?threaded\b/i, label: 'multi-threaded', absolute: false },
+  { pattern: /\bmultithreaded\b/i, label: 'multithreaded', absolute: false },
+  { pattern: /\batomic\b/i, label: 'atomic', absolute: false },
+  { pattern: /\bsynchronized\b/i, label: 'synchronized', absolute: false },
+  { pattern: /\bmutex\b/i, label: 'mutex', absolute: false },
+  { pattern: /\bsemaphore\b/i, label: 'semaphore', absolute: false },
+  { pattern: /\bspinlock\b/i, label: 'spinlock', absolute: false },
+  { pattern: /\bshared\s+variable\b/i, label: 'shared variable', absolute: false },
+  { pattern: /\bshared\s+memory\b/i, label: 'shared memory', absolute: false },
+  { pattern: /\bglobal\s+state\b/i, label: 'global state', absolute: false },
+  { pattern: /\breentrant\b/i, label: 'reentrant', absolute: false },
+  { pattern: /\binterrupt\s*-?\s*safe\b/i, label: 'interrupt-safe', absolute: true },
+  { pattern: /\bISR\s*-?\s*safe\b/i, label: 'ISR-safe', absolute: true },
+  { pattern: /\binterrupt\s+safety\b/i, label: 'interrupt safety', absolute: false },
+  { pattern: /\binterrupt\s+context\b/i, label: 'interrupt context', absolute: false },
+  { pattern: /\bISR\b/i, label: 'ISR', absolute: false },
+  { pattern: /\bIRQ\b/i, label: 'IRQ', absolute: false },
+  { pattern: /\bNMI\b/i, label: 'NMI', absolute: false },
+  { pattern: /\bcritical\s+section\b/i, label: 'critical section', absolute: false },
+  { pattern: /\bdisable_irq\b/i, label: 'disable_irq', absolute: false },
+  { pattern: /\benable_irq\b/i, label: 'enable_irq', absolute: false },
+  { pattern: /\bspin_lock_irqsave\b/i, label: 'spin_lock_irqsave', absolute: false },
+]
+
+export function runConcurrencyScan(text: string): ConcurrencyScanReport {
+  const lines = text.split(/\r?\n/)
+  const findings: ConcurrencyFinding[] = []
+  const seen = new Set<string>()
+  lines.forEach((line, index) => {
+    const lineNumber = index + 1
+    const lower = line.toLowerCase()
+    for (const rule of KEYWORD_RULES) {
+      if (!rule.pattern.test(line)) continue
+      const key = rule.label + ':' + lineNumber
+      if (seen.has(key)) continue
+      seen.add(key)
+      const finding: ConcurrencyFinding = {
+        code: rule.absolute ? 'CONCURRENCY_ABSOLUTE_CLAIM' : 'CONCURRENCY_KEYWORD',
+        severity: rule.absolute ? 'error' : 'warning',
+        message: rule.absolute
+          ? 'Concurrency safety claim "' + rule.label + '" detected; this requires dedicated verification (TSan, model checker, or explicit proof).'
+          : 'Concurrency-related term "' + rule.label + '" detected; review whether the plan addresses this risk.',
+        line: lineNumber,
+        snippet: line.trim().slice(0, 200),
+        keyword: rule.label,
+      }
+      findings.push(finding)
+    }
+  })
+  const errors = findings.filter((finding) => finding.severity === 'error').length
+  const warnings = findings.filter((finding) => finding.severity === 'warning').length
+  const absoluteClaims = findings.filter((finding) => finding.code === 'CONCURRENCY_ABSOLUTE_CLAIM').length
+  return {
+    ok: true,
+    findings,
+    summary: {
+      lines: lines.length,
+      keywords: findings.length,
+      absoluteClaims,
+      warnings,
+      errors,
+    },
+  }
+}