@ccdd/core 3.3.1 → 4.1.0

package/README.md

@@ -1,94 +1,101 @@
 # CCDD
 
-[![npm: @ccdd/project](https://img.shields.io/npm/v/@ccdd/project?logo=npm&label=%40ccdd%2Fproject)](https://www.npmjs.com/package/@ccdd/project)
-[![CDD concept](https://img.shields.io/badge/CDD-Concept-3976c7)](https://cdd.boardsketch.com)
+**Let verification define the project.** Give each Artifact its own criteria and the tools a reviewer needs to inspect it. An Artifact can be code, tests, a specification, an image or any other folder of project material.
 
-**Check that the pieces of your project fit together.**
+Put a `ccdd.json` in that folder. It owns the Artifact's name, view tools and Critics. CCDD finds those declarations, connects references and collects actual review evidence.
 
-A project has requirements, designs, tests, and implementations. CCDD connects these pieces to the checks that review them. An AI agent can compare a design with its requirements, a person can inspect an image, and a test runner can check an implementation.
-
-You choose the materials, the review criteria, and the tools reviewers can use. CCDD keeps track of what was reviewed and which checks are still needed.
-
-## How it fits together
-
-**Blue dashed lines: configuration. Orange solid lines: requests and reviews.**
-
-![CCDD: a Critic DAG, customizable Artifact types and tools, Validation, and Pi-based AI agents, people, and test runners.](.github/assets/how-it-fits-together.png)
-
-Three terms explain the picture:
-
-| Term | Meaning | Example |
-| --- | --- | --- |
-| **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. |
-
-Each Critic declares its target and references. These relationships form a directed acyclic graph, or **DAG**: checks can branch and join, but cannot depend on themselves through a cycle. Design and Tests connect to Implementation through separate Critic lines. Requirements are an explicitly accepted starting point in this example.
-
-## What you do
-
-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.
-
-For example, a document tool registered as `read` becomes `read_spec` when connected to the `spec` Artifact. CCDD gives the Agent its name, description, and input schema. When the Agent calls it, CCDD invokes your local `execute` function against the fixed review input and returns the content to the Agent.
+```text
+project/
+  why/ccdd.json
+  spec/ccdd.json
+  tests/ccdd.json
+  implementation/ccdd.json
+```
 
-Artifact types act as plugin slots through explicit registration. Importing a tool library does not register or run its tools. Agent and Human tools are registered separately; Runtime reviewers execute configured Node tests against the declared inputs.
+A Critic can ask an Agent to compare Spec with Why, ask a person to compare two images, or run tests against an implementation. It belongs to the Artifact it evaluates. References such as `{spec}` connect it to the other Artifacts it uses.
+
+```mermaid
+flowchart LR
+  subgraph Project[Your project]
+    Why[Why] -. instruction .-> Spec[Spec]
+    Spec -. instruction .-> Tests[Tests]
+    Tests -. mount / instruction .-> Implementation[Implementation]
+  end
+  Project -. folder declarations .-> CCDD
+  CCDD --> Agent[Agent review]
+  CCDD --> Human[Human review]
+  CCDD --> Runtime[Runtime tests]
+  Agent --> Evidence[Actual evidence]
+  Human --> Evidence
+  Runtime --> Evidence
+  Evidence --> CCDD
+  style Project fill:#eef6ff,stroke:#5c83aa
+  style CCDD fill:#eef9ef,stroke:#588060
+```
 
-## Try your first review
+These relationships define required input and verification, not execution order. Mutual dependencies are allowed: both Critics may run together, and final validation requires both matching results. Child Artifact folders are automatic dependencies. Logical `mounts` connect other folders without copies or symlinks.
 
-CCDD supports **Node.js 22 LTS (22.19.0 or later)**. Use the latest patch of a supported LTS release.
+## Start with a runtime check
 
-For published packages, install:
+Use Node.js 22 LTS, version 22.19.0 or later.
 
 ```sh
-npm install --ignore-scripts @ccdd/core @ccdd/project
+npm install --ignore-scripts @ccdd/core@^4 @ccdd/project@^4
 ```
 
-Follow [Your first review](docs/getting-started.md) for a complete, small example that runs a real test without an AI account. It also covers installation from local packages when a version has not been published.
+Inside an Artifact folder, create `ccdd.json`:
+
+```json
+{
+  "name": "implementation",
+  "critics": [{
+    "id": "tests",
+    "title": "Pass the implementation tests",
+    "profile": { "kind": "runtime", "command": "node", "args": ["--test", "check.test.mjs"] },
+    "payload": { "instruction": "Run the tests for {implementation}." }
+  }]
+}
+```
 
-Once your project has a configuration, the usual loop is:
+Add your actual `check.test.mjs`, then run from the workspace root:
 
 ```sh
-npx ccdd-project status
+npx ccdd-project config check
 npx ccdd-project plan implementation --recursive
 npx ccdd-project verify implementation --recursive --wait
-npx ccdd-project history implementation
+npx ccdd-project status implementation
 ```
 
-`status` and `plan` explain what is needed without starting reviews. `verify --recursive` includes any required earlier checks. To review only the selected scope, omit `--recursive`; blocked checks are reported as incomplete.
-
-## What you get back
+The [getting-started guide](docs/getting-started.md) includes a complete runnable example. Version 4 is a breaking change; existing projects should follow the [migration guide](docs/migration-v4.md).
 
-A completed review contains a **verdict, a summary, and concrete evidence**. GREEN means that Critic's criteria were met; RED means they were not. An execution problem is reported as ERROR. All required Critics must pass before their Artifact satisfies a dependent check.
+## Read the result
 
-CCDD can reuse an actual passing review when its criteria, target, and direct reference materials still match and its dependencies are satisfied. An unchanged intermediate Artifact can therefore prevent unnecessary downstream reviews.
+Every actual review returns a verdict, summary and concrete evidence. GREEN means its criteria were met; RED means they were not. Execution problems produce ERROR. Final validation needs matching PASS evidence for all required Critics and dependencies. A folder without Critics stays UNREVIEWED unless explicitly declared `basis: true`.
 
-Reviews use a fixed copy of the project by default. Records and generated output live outside the reviewed project. You can keep editing the original while a copied review runs. Reviewers inspect and judge; you or your coding tools make the changes.
+An individual check runs its selected Critics immediately. If other required evidence is missing, their results are saved and the request is INCOMPLETE. Add `--recursive` to include those other evaluations. CCDD reuses matching actual evidence and computes freshness when queried; it does not store stale flags.
 
-## Choose your next step
+Reviews run in the workspace you supply. Keep it unchanged until completion, including Human waiting. Records, caches and generated output live outside it. To keep editing elsewhere, create your own worktree and pass it with `--repo`.
 
-- [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).
+## Next steps
 
-An optional local monitor shows current-input checks and saved reviews. Start it with `npx ccdd-project monitor`.
+- [Define a custom view script](examples/custom-text-reader/README.md) with JSON stdin/stdout, using any language.
+- [Register optional text, image and desktop tools](packages/default-tools/README.md).
+- [Compose folders and mounts](examples/artifact-folders/README.md), including coding-style and blind image comparison Critics.
+- [Compute views on demand](examples/computed-views/README.md) from scenario material.
+- [Configure Agent and Human reviewers](docs/reviewers.md).
+- [Try Why → Spec → Tests → Implementation](docs/demo.md).
+- [Look up commands and evidence rules](docs/project-validation.md).
 
-## Packages and development
+The optional local monitor shows folders, relationships, cycles, review progress and saved results. Start it with `npx ccdd-project monitor`.
 
-| Package | Purpose |
+| Package | Responsibility |
 | --- | --- |
-| `@ccdd/core` | Define Artifacts, Critics, and tools. |
-| `@ccdd/project` | Run the CLI, manage reviews, and view their history. |
-| `@ccdd/default-tools` | Optional ready-made Artifact tools. |
+| `@ccdd/core` | Public definitions and logical path resolution. |
+| `@ccdd/project` | Validation, CLI, Broker, Executors and monitor. |
+| `@ccdd/default-tools` | Optional common view scripts; no automatic registration. |
 
-The repository, examples, CLI, monitor, and built-in review instructions use English. See [Contributing](CONTRIBUTING.md) for setup and checks, [the context map](CONTEXT-MAP.md) for architecture, and [release instructions](docs/releases.md) for packaging and publication.
+See [Contributing](CONTRIBUTING.md), [the context map](CONTEXT-MAP.md), [detailed contracts](docs/contracts.md) and [release instructions](docs/releases.md). Repository content and review prompts use English.
 
 ## License
 
-Licensed under the [MIT License](LICENSE).
+[MIT](LICENSE).

package/dist/src/artifact-scope.d.ts

@@ -0,0 +1,6 @@
+import type { ArtifactScope } from './definitions.js';
+/** Resolve logical paths without a filesystem. Every hop consumes path components. */
+export declare function resolveScopePath(scope: ArtifactScope, artifactId: string, path?: string): {
+    artifactId: string;
+    path: string;
+};

package/dist/src/artifact-scope.js

@@ -0,0 +1,27 @@
+/** Resolve logical paths without a filesystem. Every hop consumes path components. */
+export function resolveScopePath(scope, artifactId, path = '') {
+    if (typeof path !== 'string' || path.length > 4096 || /[\\\x00-\x1f\x7f:]/.test(path) || path.startsWith('/') || path.split('/').some(part => part === '.' || part === '..' || !part && path !== ''))
+        throw new Error('Artifact path must be a safe relative logical path.');
+    let current = artifactId, remaining = path;
+    for (;;) {
+        if (!Object.hasOwn(scope, current))
+            throw new Error(`Artifact is outside this review: ${current}`);
+        const entry = scope[current];
+        if (!remaining)
+            return { artifactId: current, path: '' };
+        const first = remaining.split('/')[0];
+        if (Object.hasOwn(entry.mounts, first)) {
+            current = entry.mounts[first];
+            remaining = remaining.slice(first.length).replace(/^\//, '');
+            continue;
+        }
+        const child = Object.keys(entry.children).find(name => remaining === name || remaining.startsWith(`${name}/`));
+        if (child !== undefined) {
+            current = entry.children[child];
+            remaining = remaining.slice(child.length).replace(/^\//, '');
+            continue;
+        }
+        return { artifactId: current, path: remaining };
+    }
+}
+//# sourceMappingURL=artifact-scope.js.map

package/dist/src/artifact-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-scope.js","sourceRoot":"","sources":["../../src/artifact-scope.ts"],"names":[],"mappings":"AAEA,sFAAsF;AACtF,MAAM,UAAU,gBAAgB,CAAC,KAAoB,EAAE,UAAkB,EAAE,IAAI,GAAG,EAAE;IAClF,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,IAAI,IAAI,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,EAAE,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IAC7Q,IAAI,OAAO,GAAG,UAAU,EAAE,SAAS,GAAG,IAAI,CAAC;IAC3C,SAAS,CAAC;QACR,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,OAAO,EAAE,CAAC,CAAC;QACnG,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7B,IAAI,CAAC,SAAS;YAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QACzD,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACtC,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;YACvC,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAAC,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAAC,SAAS;QACxG,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,SAAS,KAAK,IAAI,IAAI,SAAS,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC;QAC/G,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAAC,OAAO,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YAAC,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAAC,SAAS;QAAC,CAAC;QACrI,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAClD,CAAC;AACH,CAAC"}

package/dist/src/definitions.d.ts

@@ -1,4 +1,5 @@
-/** The definition package has no dependency on persistence or review execution. */
+import type { ArtifactViews, EnvironmentRequirement } from './tools/contracts.js';
+/** Public declarations contain data only; discovery never executes code. */
 export interface AgentProfile {
     kind: 'agent';
     provider: string;
@@ -23,8 +24,6 @@ export interface ReviewPayload {
 export interface CriticDefinition {
     id: string;
     title: string;
-    target: string;
-    deps: string[];
     profile: CriticProfile;
     payload: ReviewPayload;
 }
@@ -34,32 +33,43 @@ export type StaleStrategy = {
 } | {
     kind: 'always';
 };
-export interface ArtifactDefinition {
-    type: string;
-    path: string;
+export interface ArtifactManifest {
+    name: string;
+    critics?: CriticDefinition[];
+    views?: ArtifactViews;
+    mounts?: Record<string, string>;
     basis?: boolean;
     stale?: StaleStrategy;
+    envRequirements?: Record<string, EnvironmentRequirement>;
 }
-export interface ArtifactGroupDefinition {
-    kind: 'group';
-    members: string[];
+export interface ArtifactDefinition {
+    name: string;
+    path: string;
+    views: ArtifactViews;
+    mounts: Record<string, string>;
+    /** Nearest marked descendants, indexed by their physical relative paths. */
+    children: Record<string, string>;
     basis?: boolean;
     stale?: StaleStrategy;
+    envRequirements?: Record<string, EnvironmentRequirement>;
 }
-/** Generated material is captured separately from configuration evaluation. */
-export interface GeneratedArtifactDefinition {
-    kind: 'generated';
-    type: string;
+export interface ResolvedCriticDefinition extends CriticDefinition {
+    localId: string;
+    target: string;
+    deps: string[];
+    /** Original instruction names map to canonical Artifact identities. */
+    references: Record<string, string>;
+}
+export interface ArtifactRelation {
     source: string;
-    params?: import('./tools/contracts.js').JsonValue;
-    basis?: boolean;
-    stale?: {
-        kind: 'always';
-    };
-    path?: never;
+    target: string;
+    kind: 'child' | 'mount' | 'instruction';
+    name?: string;
+    criticId?: string;
 }
-export type ArtifactEntryDefinition = ArtifactDefinition | GeneratedArtifactDefinition | ArtifactGroupDefinition;
-export interface ArtifactGroupReference {
-    id: string;
-    members: string[];
+export interface ArtifactScopeEntry {
+    path: string;
+    children: Record<string, string>;
+    mounts: Record<string, string>;
 }
+export type ArtifactScope = Record<string, ArtifactScopeEntry>;

package/dist/src/sdk.d.ts

@@ -1,15 +1,10 @@
-import type { ArtifactSourceDefinition, DataToolContext, Config, ConfigFactory, InferSchema, JsonSchema, ToolDefinition, ToolMetadata } from './tools/contracts.js';
+import type { 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;
+export { resolveScopePath } from './artifact-scope.js';
+/** An optional script-authoring helper, not a configuration registration API. */
 export declare function defineTool<const S extends JsonSchema>(tool: Omit<ToolDefinition<InferSchema<S>>, 'metadata'> & {
     metadata: Omit<ToolMetadata, 'inputSchema'> & {
         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,5 +1,4 @@
-export function defineConfig(config) { return config; }
+export { resolveScopePath } from './artifact-scope.js';
+/** An optional script-authoring helper, not a configuration registration API. */
 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;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"}
+{"version":3,"file":"sdk.js","sourceRoot":"","sources":["../../src/sdk.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,iFAAiF;AACjF,MAAM,UAAU,UAAU,CAA6B,IAA6H,IAAoC,OAAO,IAAI,CAAC,CAAC,CAAC"}

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

@@ -1,4 +1,4 @@
-import type { ArtifactEntryDefinition, CriticDefinition } from '../definitions.js';
+import type { ArtifactDefinition, ArtifactManifest, ArtifactScope } from '../definitions.js';
 export type JsonValue = null | boolean | number | string | JsonValue[] | {
     [key: string]: JsonValue;
 };
@@ -9,21 +9,22 @@ export interface ToolMetadata {
     inputSchema: JsonSchema;
     resultKinds: ToolResultKind[];
     observation: 'content' | 'none';
-    artifactKind?: 'file' | 'directory' | 'any' | 'data';
+    artifactKind?: 'file' | 'directory' | 'any';
     timeoutMs?: number;
-    /** Project-relative runtime files or directories whose bytes affect this tool. */
+    /** Workspace-relative runtime material whose content affects this tool. */
     executionPaths?: string[];
 }
-export interface ToolContext {
-    artifactId: string;
-    artifactPath: string;
-    artifactDirectory: boolean;
-    outputDir: string;
-    tmpDir: string;
-    signal: AbortSignal;
-    resolvePath(path?: string): Promise<string>;
-    /** Resolve only paths explicitly registered in metadata.executionPaths. */
-    resolveExecutionPath?(path: string): Promise<string>;
+export interface ScriptDefinition {
+    command: string;
+    args: string[];
+}
+export interface ScriptToolDefinition {
+    metadata: ToolMetadata;
+    script: ScriptDefinition;
+}
+export interface ArtifactViews {
+    agentTools?: Record<string, ScriptToolDefinition>;
+    humanTools?: Record<string, ScriptToolDefinition>;
 }
 export type ToolContent = {
     type: 'text';
@@ -43,59 +44,40 @@ export type ToolContent = {
     type: 'launch';
     launched: true;
 };
-export interface ToolResult {
+export type ToolResult = {
     content: ToolContent[];
     observation?: {
         kind: 'content' | 'empty';
         detail?: string;
     };
-}
-/** Data tools receive only their bound, captured Artifact data. */
-export interface DataToolContext {
+    isError?: never;
+} | {
+    isError: true;
+    content: [{
+        type: 'text';
+        text: string;
+    }];
+    observation?: never;
+};
+export interface ScriptToolContext {
     artifactId: string;
+    artifactPath: string;
     outputDir: string;
     tmpDir: string;
-    signal: AbortSignal;
-    readData(): JsonValue;
-    resolveExecutionPath(path: string): Promise<string>;
+    /** Canonical paths and logical connections for this review's allowed scope. */
+    scope: ArtifactScope;
 }
-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 ScriptToolRequest {
+    version: 1;
+    context: ScriptToolContext;
+    args: Record<string, unknown>;
 }
-export interface ArtifactSourceContext {
-    artifactId: string;
-    params: JsonValue;
+/** Convenience interface for script authors. Project never imports these functions. */
+export interface ToolContext extends ScriptToolContext {
+    artifactDirectory: boolean;
     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;
+    resolvePath(path?: string): Promise<string>;
+    resolveExecutionPath?(path: string): Promise<string>;
 }
 export interface ToolDefinition<Args = Record<string, unknown>, Context = ToolContext> {
     metadata: ToolMetadata;
@@ -108,48 +90,31 @@ export interface ToolDefinition<Args = Record<string, unknown>, Context = ToolCo
         message: string;
     }>;
 }
-export interface ArtifactToolsConfig {
-    agentTools?: Record<string, ToolDefinition<any, any>>;
-    humanTools?: Record<string, ToolDefinition<any, any>>;
-}
 export interface EnvironmentRequirement {
     description: string;
-    /** Project-relative Node script; a zero exit status confirms readiness. */
     script: string;
     timeoutMs?: number;
-    /** Additional project files or directories used by the check. */
     inputs?: string[];
 }
-export interface Config {
-    artifacts: Record<string, ArtifactEntryDefinition>;
-    artifactTypes: Record<string, ArtifactToolsConfig>;
-    critics: CriticDefinition[];
-    envRequirements?: Record<string, EnvironmentRequirement>;
-    artifactSources?: Record<string, ArtifactSourceDefinition>;
-}
-export type ConfigFactory = () => Config | Promise<Config>;
 export interface ConfigManifest {
-    version: 1;
+    version: 2;
     configHash: string;
-    modules: {
+    artifacts: Record<string, ArtifactDefinition>;
+    declarations: {
         path: string;
         hash: string;
     }[];
-    types: Record<string, {
-        agentTools: Record<string, ToolMetadata>;
-        humanTools: Record<string, ToolMetadata>;
-    }>;
-    envRequirements?: Record<string, EnvironmentRequirement>;
-    environmentInputs?: {
+    executionInputs?: {
         path: string;
         hash: string;
     }[];
-    executionInputs?: {
+    envRequirements?: Record<string, EnvironmentRequirement>;
+    environmentInputs?: {
         path: string;
         hash: string;
     }[];
-    sources?: Record<string, ArtifactSourceMetadata>;
 }
+export type { ArtifactManifest };
 type Properties<S> = S extends {
     properties: infer P;
 } ? P : {};
@@ -176,4 +141,3 @@ export type InferSchema<S> = S extends {
 } & {
     [K in keyof Properties<S> as K extends RequiredKeys<S> ? never : K]?: InferSchema<Properties<S>[K]>;
 } : unknown;
-export {};

package/examples/artifact-folders/README.md

@@ -0,0 +1,18 @@
+# Folder composition and logical mounts
+
+`explosion/ccdd.json` owns the parent's tools and Critics. The nearest marked children, `effect` and `preview`, remain separate Artifacts. The parent automatically depends on both. `style` and `theme` are logical mounts to sibling Artifacts; no directories, copies or symlinks are created for them.
+
+Install `@ccdd/core`, `@ccdd/project` and `@ccdd/default-tools` in this directory, then run:
+
+```sh
+ccdd-project config check
+ccdd-project graph explosion --json
+ccdd-project tools check --artifact explosion --for agent --tool blind_pair --execute
+ccdd-project verify explosion --recursive --wait
+```
+
+The last command uses real Agent evaluation. No verdict is included in this example. The theme and screenshot intentionally use the same supplied sample image; replace them before using this as a project criterion.
+
+The coding-style Critic references `{style}` through the existing instruction template. The blind comparison procedure is a normal user script: it resolves the theme mount and preview child, randomizes A/B, returns images, and writes its private mapping to the external output directory. The Critic instructs its reviewer not to open named views. That is a review procedure, not an access-control guarantee against a reviewer who deliberately ignores it. CCDD adds no presentation-specific runner. The other Critic demonstrates direct `{effect}` and `{preview}` references.
+
+Repeated mounts share the canonical Artifact and its evidence. Each Artifact controls its own tools; parent declarations do not merge child Critics or views.