@ccdd/core 3.1.2 → 3.2.0

package/README.md

@@ -19,7 +19,7 @@ Three terms explain the picture:
 
 | Term | Meaning | Example |
 | --- | --- | --- |
-| **Artifact** | A named file, folder, or group of materials to review. | `spec.md`, `tests/`, or an image. |
+| **Artifact** | A named file, folder, captured data value, or group of materials to review. | `spec.md`, `tests/`, an image, or a generated scenario. |
 | **Critic** | A check with one target, reference materials, and a reviewer. | “Does this design meet these requirements?” |
 | **Artifact tool** | A way for a reviewer to inspect an Artifact. | Read text, view an image, or open a desktop application. |
 
@@ -27,7 +27,7 @@ Each Critic declares its target and references. These relationships form a direc
 
 ## What you do
 
-1. **Name your materials.** Give each Artifact an ID, a type, and a file or folder path. Groups collect existing Artifacts.
+1. **Name your materials.** Give each Artifact an ID, a type, and a file/folder path or a source for generated data. Groups collect existing Artifacts.
 2. **Connect tools.** Use the optional default tools or write your own `metadata` and `execute` function. Register them by Artifact type in `ccdd.config.ts`.
 3. **Define checks.** For each Critic, choose the target, its references, the review criteria, and an Agent, Human, or Runtime reviewer.
 4. **Request a review.** Read the findings, update your project, and request another check when needed.
@@ -72,6 +72,7 @@ Reviews use a fixed copy of the project by default. Records and generated output
 - [Write an Artifact tool](examples/custom-text-reader/README.md) using the public tool contract.
 - [Use default text, file, image, and desktop tools](packages/default-tools/README.md).
 - [Review a group of materials](examples/artifact-groups/README.md), such as an effect description and its preview image.
+- [Review generated scenario data](docs/generated-artifacts.md) through tools that read a fixed captured value.
 - [Use Agent and Human reviewers](docs/reviewers.md), including credentials and result submission.
 - [Explore the demo](docs/demo.md): Why → Spec → Tests → Implementation.
 - [Look up commands, reuse rules, and exit codes](docs/project-validation.md).

package/dist/src/definitions.d.ts

@@ -46,7 +46,19 @@ export interface ArtifactGroupDefinition {
     basis?: boolean;
     stale?: StaleStrategy;
 }
-export type ArtifactEntryDefinition = ArtifactDefinition | ArtifactGroupDefinition;
+/** Generated material is captured separately from configuration evaluation. */
+export interface GeneratedArtifactDefinition {
+    kind: 'generated';
+    type: string;
+    source: string;
+    params?: import('./tools/contracts.js').JsonValue;
+    basis?: boolean;
+    stale?: {
+        kind: 'always';
+    };
+    path?: never;
+}
+export type ArtifactEntryDefinition = ArtifactDefinition | GeneratedArtifactDefinition | ArtifactGroupDefinition;
 export interface ArtifactGroupReference {
     id: string;
     members: string[];

package/dist/src/sdk.d.ts

@@ -1,4 +1,4 @@
-import type { Config, ConfigFactory, InferSchema, JsonSchema, ToolDefinition, ToolMetadata } from './tools/contracts.js';
+import type { ArtifactSourceDefinition, DataToolContext, Config, ConfigFactory, InferSchema, JsonSchema, ToolDefinition, ToolMetadata } from './tools/contracts.js';
 export type * from './tools/contracts.js';
 export type * from './definitions.js';
 export declare function defineConfig<T extends Config | ConfigFactory>(config: T): T;
@@ -7,3 +7,9 @@ export declare function defineTool<const S extends JsonSchema>(tool: Omit<ToolDe
         inputSchema: S;
     };
 }): ToolDefinition<InferSchema<S>>;
+export declare function defineDataTool<const S extends JsonSchema>(tool: Omit<ToolDefinition<InferSchema<S>, DataToolContext>, 'metadata'> & {
+    metadata: Omit<ToolMetadata, 'inputSchema' | 'artifactKind'> & {
+        inputSchema: S;
+    };
+}): ToolDefinition<InferSchema<S>, DataToolContext>;
+export declare function defineArtifactSource(source: ArtifactSourceDefinition): ArtifactSourceDefinition;

package/dist/src/sdk.js

@@ -1,3 +1,5 @@
 export function defineConfig(config) { return config; }
 export function defineTool(tool) { return tool; }
+export function defineDataTool(tool) { return { ...tool, metadata: { ...tool.metadata, artifactKind: 'data' } }; }
+export function defineArtifactSource(source) { return source; }
 //# sourceMappingURL=sdk.js.map

package/dist/src/sdk.js.map

@@ -1 +1 @@
-{"version":3,"file":"sdk.js","sourceRoot":"","sources":["../../src/sdk.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,YAAY,CAAmC,MAAS,IAAO,OAAO,MAAM,CAAC,CAAC,CAAC;AAC/F,MAAM,UAAU,UAAU,CAA6B,IAA6H,IAAoC,OAAO,IAAI,CAAC,CAAC,CAAC"}
+{"version":3,"file":"sdk.js","sourceRoot":"","sources":["../../src/sdk.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,YAAY,CAAmC,MAAS,IAAO,OAAO,MAAM,CAAC,CAAC,CAAC;AAC/F,MAAM,UAAU,UAAU,CAA6B,IAA6H,IAAoC,OAAO,IAAI,CAAC,CAAC,CAAC;AACtO,MAAM,UAAU,cAAc,CAA6B,IAA+J,IAAqD,OAAO,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC;AAC1V,MAAM,UAAU,oBAAoB,CAAC,MAAgC,IAA8B,OAAO,MAAM,CAAC,CAAC,CAAC"}

package/dist/src/tools/contracts.d.ts

@@ -9,7 +9,7 @@ export interface ToolMetadata {
     inputSchema: JsonSchema;
     resultKinds: ToolResultKind[];
     observation: 'content' | 'none';
-    artifactKind?: 'file' | 'directory' | 'any';
+    artifactKind?: 'file' | 'directory' | 'any' | 'data';
     timeoutMs?: number;
     /** Project-relative runtime files or directories whose bytes affect this tool. */
     executionPaths?: string[];
@@ -50,10 +50,57 @@ export interface ToolResult {
         detail?: string;
     };
 }
-export interface ToolDefinition<Args = Record<string, unknown>> {
+/** Data tools receive only their bound, captured Artifact data. */
+export interface DataToolContext {
+    artifactId: string;
+    outputDir: string;
+    tmpDir: string;
+    signal: AbortSignal;
+    readData(): JsonValue;
+    resolveExecutionPath(path: string): Promise<string>;
+}
+export interface ArtifactIdentityStrategy {
+    kind: 'canonical-data' | 'immutable-revision' | 'custom';
+    namespace: string;
+    version: string;
+}
+export interface ArtifactSourceMetadata {
+    identity: ArtifactIdentityStrategy;
+    /** Queries may invoke only sources explicitly declaring read-only preparation. */
+    preparation: 'read-only' | 'explicit';
+    timeoutMs?: number;
+}
+export interface ArtifactSourceContext {
+    artifactId: string;
+    params: JsonValue;
+    signal: AbortSignal;
+    /** Resolve captured project files, never the mutable original copy source. */
+    resolvePath(path: string): Promise<string>;
+}
+export interface ArtifactSourceResult {
+    data: JsonValue;
+    revision?: string;
+}
+export interface ArtifactSourceDefinition {
+    metadata: ArtifactSourceMetadata;
+    prepare(context: ArtifactSourceContext): ArtifactSourceResult | Promise<ArtifactSourceResult>;
+    /** A custom identity asserts equivalence of the complete supplied data. */
+    fingerprint?(data: JsonValue): string | Promise<string>;
+}
+export interface PreparedArtifactData {
+    version: 1;
+    identity: ArtifactIdentityStrategy & {
+        fingerprint: string;
+    };
+    /** Integrity hash of the canonical data, independent of semantic equivalence. */
+    contentHash: string;
+    data: JsonValue;
+    revision?: string;
+}
+export interface ToolDefinition<Args = Record<string, unknown>, Context = ToolContext> {
     metadata: ToolMetadata;
-    execute(context: ToolContext, args: Args): ToolResult | Promise<ToolResult>;
-    preflight?(context: ToolContext): {
+    execute(context: Context, args: Args): ToolResult | Promise<ToolResult>;
+    preflight?(context: Context): {
         ok: boolean;
         message: string;
     } | Promise<{
@@ -62,8 +109,8 @@ export interface ToolDefinition<Args = Record<string, unknown>> {
     }>;
 }
 export interface ArtifactToolsConfig {
-    agentTools?: Record<string, ToolDefinition<any>>;
-    humanTools?: Record<string, ToolDefinition<any>>;
+    agentTools?: Record<string, ToolDefinition<any, any>>;
+    humanTools?: Record<string, ToolDefinition<any, any>>;
 }
 export interface EnvironmentRequirement {
     description: string;
@@ -78,6 +125,7 @@ export interface Config {
     artifactTypes: Record<string, ArtifactToolsConfig>;
     critics: CriticDefinition[];
     envRequirements?: Record<string, EnvironmentRequirement>;
+    artifactSources?: Record<string, ArtifactSourceDefinition>;
 }
 export type ConfigFactory = () => Config | Promise<Config>;
 export interface ConfigManifest {
@@ -100,6 +148,7 @@ export interface ConfigManifest {
         path: string;
         hash: string;
     }[];
+    sources?: Record<string, ArtifactSourceMetadata>;
 }
 type Properties<S> = S extends {
     properties: infer P;

package/examples/generated-artifacts/README.md

@@ -0,0 +1,55 @@
+# Review generated scenario data
+
+This example captures two JSON scenarios as independent generated Artifacts. The scenario files are sample evidence for demonstrating review mechanics, not recorded product tests. Each Human Critic must inspect an overview and every listed detail, then make an actual judgment.
+
+`scenarioSource.prepare` reads a file from the captured project through `context.resolvePath`. It returns structured data directly; CCDD persists the fixed value outside the reviewed workspace. The source does no generation, so it declares `preparation: 'read-only'` and supports `status` and `plan`.
+
+The explicitly registered `overview` and `detail` tools use `context.readData()`. Each call receives a copy of the recorded value, including after worker restart. The full scenario determines identity even when a tool only returns one field. Initial prompts and monitor scope metadata do not contain that data.
+
+## Run the example
+
+Use Node 22 LTS, at least 22.19.0. These APIs require CCDD 3.2.0 or later. From the source repository, build and pack core and project:
+
+```sh
+npm ci
+npm run build
+CCDD_GENERATED_PACKAGES=$(mktemp -d /tmp/ccdd-generated-packages.XXXXXX)
+npm pack --ignore-scripts --pack-destination "$CCDD_GENERATED_PACKAGES"
+npm pack --ignore-scripts --workspace @ccdd/project --pack-destination "$CCDD_GENERATED_PACKAGES"
+
+CCDD_GENERATED_EXAMPLE=$(mktemp -d /tmp/ccdd-generated-example.XXXXXX)
+cp -R examples/generated-artifacts "$CCDD_GENERATED_EXAMPLE/project"
+cd "$CCDD_GENERATED_EXAMPLE/project"
+npm init -y
+npm pkg set type=module
+npm install --ignore-scripts "$CCDD_GENERATED_PACKAGES"/*.tgz
+```
+
+Inspect the current input and execute the two data tools without starting a review:
+
+```sh
+npx ccdd-project plan checkout
+npx ccdd-project tools check --artifact checkout --for human --tool overview --execute
+npx ccdd-project tools check --artifact checkout --for human --tool detail --execute --args '{"id":"summary"}'
+```
+
+These tool diagnostics prepare a new snapshot and report actual tool results. They do not create a verdict or demonstrate that the scenario passes its Critic.
+
+Request both Human reviews and open the monitor:
+
+```sh
+npx ccdd-project verify --all --human-inbox
+npx ccdd-project monitor
+```
+
+Open the printed local address, choose the project and a Human request, and claim it. Execute `overview`, then call `detail` for every returned detail ID. Submit your verdict with a summary and evidence citing those IDs. Repeat for the other scenario. See the [Human reviewer guide](../../docs/reviewers.md#ask-a-person-to-review) for the claim and submission workflow.
+
+The tools are also registered for Agents. To use them, change the desired Critic to an explicitly supported Agent profile and supply credentials as described in the [reviewer guide](../../docs/reviewers.md). An Agent review makes actual Provider calls. Runtime Critics do not support generated Artifact scopes.
+
+## Inspect reuse
+
+After completing real reviews, run `npx ccdd-project status`. Edit a detail in `scenarios/checkout.json` and run `npx ccdd-project plan --all`. Checkout now has changed input; an applicable passing search review can remain reusable because its captured data and Critic definition are unchanged. Changing an unread detail also changes checkout identity. Restoring equivalent checkout data can reuse its applicable historical evidence, subject to the existing latest-verdict and dependency rules.
+
+Changing whitespace or object-key order preserves canonical JSON identity. Array order remains significant. Keep changing scenario data in these source files rather than importing it into shared config: imported config module changes conservatively affect effective Critic definitions.
+
+See [generated Artifact contracts](../../docs/generated-artifacts.md) for identity strategies, canonicalization, size limits, preparation policy, and reopening behavior.

package/examples/generated-artifacts/ccdd.config.ts

@@ -0,0 +1,86 @@
+import { readFile } from 'node:fs/promises';
+import { defineArtifactSource, defineConfig, defineDataTool } from '@ccdd/core';
+import type { JsonValue } from '@ccdd/core';
+
+function scenarioData(value: JsonValue) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || typeof value.name !== 'string' || typeof value.objective !== 'string'
+    || !Array.isArray(value.criteria) || value.criteria.some(item => typeof item !== 'string')
+    || !Array.isArray(value.details) || value.details.some(item => !item || typeof item !== 'object'
+      || Array.isArray(item) || typeof item.id !== 'string' || typeof item.observation !== 'string')) {
+    throw new Error('Expected a scenario with name, objective, criteria, and identified details.');
+  }
+  return value as { name: string; objective: string; criteria: string[]; details: { id: string; observation: string }[] };
+}
+
+const scenarioSource = defineArtifactSource({
+  metadata: {
+    preparation: 'read-only',
+    identity: { kind: 'canonical-data', namespace: 'example/scenario', version: '1' },
+  },
+  async prepare(context) {
+    if (typeof context.params !== 'string') throw new Error('Expected a scenario file path.');
+    const data: JsonValue = JSON.parse(await readFile(await context.resolvePath(context.params), 'utf8'));
+    scenarioData(data);
+    return { data };
+  },
+});
+
+const overview = defineDataTool({
+  metadata: {
+    description: 'Read the objective, criteria, and available detail IDs of {artifactName}.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    resultKinds: ['json'],
+    observation: 'content',
+  },
+  execute(context) {
+    const data = scenarioData(context.readData());
+    return {
+      content: [{ type: 'json', data: {
+        name: data.name, objective: data.objective, criteria: data.criteria,
+        detailIds: data.details.map(detail => detail.id),
+      } }],
+      observation: { kind: 'content' },
+    };
+  },
+});
+
+const detail = defineDataTool({
+  metadata: {
+    description: 'Read one identified detail from the captured {artifactName} scenario.',
+    inputSchema: {
+      type: 'object', properties: { id: { type: 'string', minLength: 1 } },
+      required: ['id'], additionalProperties: false,
+    },
+    resultKinds: ['json'],
+    observation: 'content',
+  },
+  execute(context, args) {
+    const found = scenarioData(context.readData()).details.find(item => item.id === args.id);
+    if (!found) throw new Error('Unknown scenario detail.');
+    return { content: [{ type: 'json', data: found }], observation: { kind: 'content' } };
+  },
+});
+
+export default defineConfig({
+  artifactSources: { scenario: scenarioSource },
+  artifactTypes: {
+    scenario: { agentTools: { overview, detail }, humanTools: { overview, detail } },
+  },
+  artifacts: {
+    checkout: { kind: 'generated', type: 'scenario', source: 'scenario', params: 'scenarios/checkout.json' },
+    search: { kind: 'generated', type: 'scenario', source: 'scenario', params: 'scenarios/search.json' },
+  },
+  critics: [
+    {
+      id: 'checkout-review', title: 'Review the checkout scenario', target: 'checkout', deps: [],
+      profile: { kind: 'human' },
+      payload: { instruction: 'Read the overview of {checkout}, then inspect every listed detail. Decide whether the observations satisfy each criterion. Cite detail IDs and explain missing or contradictory evidence.' },
+    },
+    {
+      id: 'search-review', title: 'Review the search scenario', target: 'search', deps: [],
+      profile: { kind: 'human' },
+      payload: { instruction: 'Read the overview of {search}, then inspect every listed detail. Decide whether the observations satisfy each criterion. Cite detail IDs and explain missing or contradictory evidence.' },
+    },
+  ],
+});

package/examples/generated-artifacts/scenarios/checkout.json

@@ -0,0 +1,12 @@
+{
+  "name": "Guest checkout",
+  "objective": "A guest can review the total before placing an order.",
+  "criteria": [
+    "The order summary shows both shipping and the final total.",
+    "The guest can return to the cart before placing the order."
+  ],
+  "details": [
+    { "id": "summary", "observation": "The summary shows items at $20, shipping at $5, and a final total of $25." },
+    { "id": "navigation", "observation": "A Back to cart link appears beside the Place order button." }
+  ]
+}

package/examples/generated-artifacts/scenarios/search.json

@@ -0,0 +1,12 @@
+{
+  "name": "Empty search results",
+  "objective": "A user can recover from a search that finds no items.",
+  "criteria": [
+    "The result view states that no items match the search.",
+    "The user can change the query without leaving the result view."
+  ],
+  "details": [
+    { "id": "message", "observation": "The result heading reads No matching items." },
+    { "id": "query", "observation": "The original query remains in an editable search field above the heading." }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccdd/core",
-  "version": "3.1.2",
+  "version": "3.2.0",
   "license": "MIT",
   "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
   "repository": { "type": "git", "url": "git+https://github.com/lhj6102/ccdd.git" },