dsh-policy-ledger 0.0.0-stage → 0.2.0-alpha.3

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+dsh-policy-ledger
+Copyright 2026 PerryLink
+
+Uses fflate (MIT) and zod (MIT). Public demo uses synthetic package tarballs;
+no customer profile, registry token, or private package is included.

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# dsh-policy-ledger
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read-only capability snapshot, tarball assert and install diagnosis for DeepSeek Harness.
+
+> **Status: alpha / public-synthetic / partial / not counted / not GA.** No customer evidence, customer data, or production-readiness claim. All acceptance rows are `counted=false`.
+
+## Install
+
+```sh
+dsh plugin --profile <profile> add dsh-policy-ledger
+dsh --profile <profile> --dump-config | grep dsh-policy-ledger
+```
+
+CLI:
+
+```sh
+dsh-policy-ledger doctor ./some-package.tgz --json
+```
+
+Requires DSH `>=0.2.1-rc.3 <0.3.0` and Node `>=24.9 <25`.
+
+<details>
+<summary>中文摘要</summary>
+
+只读安装诊断：能力快照、tarball 断言与安装日志分类。 安装：`dsh plugin --profile <profile> add dsh-policy-ledger`。公开/合成、alpha、非 GA。
+
+</details>
+
+## Tools
+
+| Tool | What it does | Risk |
+|---|---|---|
+| `trust.capability_snapshot` | Extract declared capabilities and R0–R3 risk from a local npm `.tgz`: tools, bundle/client/bin/skill, build scripts, outbound hosts, credential references | R0 local read |
+| `trust.diff` | Compare two stored snapshots: added/removed capabilities, risk escalation, blockers | R0 |
+| `trust.assert_tarball` | Re-read a tarball and compare it with a stored snapshot: pass/missing/extra/changed/unknown | R0 |
+| `install.diagnose` | Classify an install log into stage, root cause and three actions; return unknown rather than guess | R0 |
+| `install.probe` | Check disk free, write permission, proxy, optional registry RTT, node/pnpm | R0 |
+| `install.bundle` | Write a redacted incident ZIP (diagnosis + evidence lines) | R1 local write |
+
+## Input / output
+
+**Input:** a local npm `.tgz`, a stored snapshot, an install log, or the local environment. **Output:** a capability snapshot, snapshot diff, tarball assert result, install diagnosis, environment probe, or redacted incident ZIP. The CLI exposes `dsh-policy-ledger doctor <tgz> --json`.
+
+## Configuration
+
+| Env | Default | Meaning |
+|---|---|---|
+| `DSH_TRUST_HOME` | `$DSH_HOME/storages/dsh-policy-ledger` | bundles and local storage |
+| `DSH_TRUST_INPUT_ROOTS` | `current working directory` | tarball allowlist |
+
+## Limits / non-claims
+
+- This is **not** a policy ledger, Gate, ledger, rollback, retry, or profile five-state product; the package name is retained for npm continuity.
+- No signing root, no policy evaluation/apply/rollback/receipt, no Client, Skill, or Bundle surface.
+- No customer profile, registry token, or private package is included.
+- `install.bundle` writes a local redacted ZIP; it does not upload anything.
+- No customer evidence, customer data, or production-readiness claim; all fixtures are public/synthetic.
+
+## Public sample
+
+Public/synthetic tarballs and install-log fixtures; `ACCEPTANCE.csv` lists 4 public checks. No customer profile is included.
+
+## Development
+
+```sh
+pnpm install --frozen-lockfile
+pnpm build && pnpm lint && pnpm typecheck && pnpm test && pnpm gate:sku03
+```
+
+## License
+
+Apache-2.0. See `LICENSE`, `NOTICE`, `THIRD-PARTY-NOTICES`.

package/THIRD-PARTY-NOTICES

@@ -0,0 +1,6 @@
+Third-party notices for dsh-policy-ledger
+
+- fflate (MIT)
+- zod (MIT)
+
+No customer profiles, registry tokens, or private packages are included.

package/bin/dsh-policy-ledger.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/** Minimal CLI: dsh-policy-ledger doctor <package.tgz> [--json] */
+import { readFileSync } from 'node:fs'
+import { inspectPackageTarball } from '../lib/adapters/tarball.js'
+
+const args = process.argv.slice(2)
+const command = args[0]
+if (command !== 'doctor' || !args[1]) {
+  console.error('usage: dsh-policy-ledger doctor <package.tgz> [--json]')
+  process.exit(64)
+}
+const file = args[1]
+try {
+  const snapshot = inspectPackageTarball(readFileSync(file), file)
+  if (args.includes('--json')) {
+    console.log(JSON.stringify(snapshot, null, 2))
+  } else {
+    console.log(`package: ${snapshot.name}@${snapshot.version}`)
+    console.log(`risk: ${snapshot.risk} (extractor ${snapshot.extractor_version})`)
+    console.log(`capabilities: ${snapshot.caps.length}`)
+    for (const cap of snapshot.caps) console.log(`  - ${cap.kind}: ${cap.name}${cap.detail ? ` (${cap.detail})` : ''}`)
+    if (snapshot.outbound_hosts.length) console.log(`outbound hosts: ${snapshot.outbound_hosts.join(', ')}`)
+    if (snapshot.build_scripts.length) console.log(`build scripts: ${snapshot.build_scripts.join(', ')}`)
+    if (snapshot.unknowns.length) console.log(`unknowns: ${snapshot.unknowns.join('; ')}`)
+  }
+  process.exit(snapshot.risk === 'R3' ? 2 : 0)
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exit(1)
+}

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-policy-ledger
+      name: 'dsh-policy-ledger'

package/lib/adapters/tarball.d.ts

@@ -0,0 +1,2 @@
+import { type Snapshot } from '../core/trust.js';
+export declare function inspectPackageTarball(buffer: Buffer, specLabel?: string): Snapshot;

package/lib/adapters/tarball.js

@@ -0,0 +1,151 @@
+import { createHash } from 'node:crypto';
+import { gunzipSync } from 'node:zlib';
+import { EXTRACTOR_VERSION, TrustError, canonicalJson, riskFromCaps, } from '../core/trust.js';
+const MAX_PARTS = 5000;
+const MAX_BYTES = 100 * 1024 * 1024;
+function sha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+function parseOctal(bytes) {
+    const value = Buffer.from(bytes).toString('ascii').replace(/\0/g, '').trim();
+    if (!value)
+        return 0;
+    const parsed = Number.parseInt(value, 8);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function tarEntries(buffer) {
+    let tar;
+    try {
+        tar = gunzipSync(buffer);
+    }
+    catch {
+        throw new TrustError('E_TRUST_TARBALL_INVALID', 'not a gzip-compressed npm tarball');
+    }
+    const entries = new Map();
+    let offset = 0;
+    let total = 0;
+    while (offset + 512 <= tar.length) {
+        const header = tar.subarray(offset, offset + 512);
+        if (header.every((byte) => byte === 0))
+            break;
+        let name = header.subarray(0, 100).toString('utf8').replace(/\0.*$/, '');
+        const prefix = header.subarray(345, 500).toString('utf8').replace(/\0.*$/, '');
+        if (prefix)
+            name = `${prefix}/${name}`;
+        const size = parseOctal(header.subarray(124, 136));
+        const type = String.fromCharCode(header[156] ?? 0);
+        offset += 512;
+        if (size < 0 || offset + size > tar.length)
+            throw new TrustError('E_TRUST_TARBALL_INVALID', 'truncated tar entry');
+        if (type === '0' || type === '\0') {
+            if (name.startsWith('package/')) {
+                const relative = name.slice('package/'.length);
+                if (relative)
+                    entries.set(relative, tar.subarray(offset, offset + size));
+                total += size;
+                if (entries.size > MAX_PARTS)
+                    throw new TrustError('E_TRUST_TARBALL_LIMIT', `too many entries: ${entries.size}`);
+                if (total > MAX_BYTES)
+                    throw new TrustError('E_TRUST_TARBALL_LIMIT', 'uncompressed tarball too large');
+            }
+        }
+        offset += Math.ceil(size / 512) * 512;
+    }
+    return entries;
+}
+function textOf(entries, name) {
+    const value = entries.get(name);
+    return value ? Buffer.from(value).toString('utf8') : undefined;
+}
+function hostsOf(text) {
+    const hosts = new Set();
+    for (const match of text.matchAll(/https?:\/\/([^/\s"'<>]+)/g)) {
+        const host = (match[1] ?? '').toLowerCase();
+        if (!host)
+            continue;
+        if (['github.com', 'www.npmjs.com', 'npmjs.com', 'registry.npmjs.org', 'www.w3.org', 'schemas.openxmlformats.org', 'json-schema.org', 'opensource.org'].includes(host))
+            continue;
+        hosts.add(host);
+    }
+    return [...hosts].sort();
+}
+function credsOf(text) {
+    const creds = new Set();
+    for (const match of text.matchAll(/\b(Authorization|API[_-]?KEY|ACCESS[_-]?TOKEN|SECRET[_-]?KEY|PASSWORD|CREDENTIALS?)\b/gi)) {
+        creds.add(match[1].toUpperCase());
+    }
+    return [...creds].sort();
+}
+export function inspectPackageTarball(buffer, specLabel) {
+    if (buffer.length === 0)
+        throw new TrustError('E_TRUST_FILE_UNREADABLE', 'empty tarball');
+    const entries = tarEntries(buffer);
+    const packageJsonText = textOf(entries, 'package.json');
+    if (!packageJsonText)
+        throw new TrustError('E_TRUST_TARBALL_INVALID', 'tarball has no package/package.json');
+    let pkg;
+    try {
+        pkg = JSON.parse(packageJsonText);
+    }
+    catch {
+        throw new TrustError('E_TRUST_TARBALL_INVALID', 'package.json is not valid JSON');
+    }
+    const name = typeof pkg.name === 'string' ? pkg.name : '';
+    const version = typeof pkg.version === 'string' ? pkg.version : '';
+    if (!name || !version)
+        throw new TrustError('E_TRUST_TARBALL_INVALID', 'package.json lacks name/version');
+    const dsh = pkg.dsh && typeof pkg.dsh === 'object' ? pkg.dsh : {};
+    const scripts = pkg.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
+    const bin = pkg.bin && typeof pkg.bin === 'object' ? Object.keys(pkg.bin) : [];
+    const caps = [];
+    if (dsh.bundle)
+        caps.push({ kind: 'bundle', name: 'dsh.bundle', detail: 'bundle patch' });
+    if (dsh.client)
+        caps.push({ kind: 'client', name: 'dsh.client', detail: 'web client' });
+    for (const command of bin)
+        caps.push({ kind: 'bin', name: command });
+    if (Array.isArray(dsh.skills))
+        for (const skill of dsh.skills)
+            caps.push({ kind: 'skill', name: String(skill) });
+    const sourceEntries = [...entries.entries()].filter(([entry]) => /\.(?:js|mjs|cjs|ts|tsx|jsx)$/.test(entry));
+    const sourceText = sourceEntries.map(([, bytes]) => Buffer.from(bytes).toString('utf8')).join('\n');
+    const toolNames = new Set();
+    for (const match of sourceText.matchAll(/defineTool\s*\(\s*\{[\s\S]{0,500}?name\s*:\s*['"]([^'"]+)['"]/g))
+        toolNames.add(match[1]);
+    for (const tool of toolNames)
+        caps.push({ kind: 'tool', name: tool });
+    const buildScripts = ['preinstall', 'install', 'postinstall', 'prepare'].filter((key) => typeof scripts[key] === 'string');
+    for (const script of buildScripts)
+        caps.push({ kind: 'build-script', name: script, detail: String(scripts[script]) });
+    const allText = [packageJsonText, textOf(entries, 'README.md') ?? '', sourceText].join('\n');
+    const outboundHosts = hostsOf(allText);
+    for (const host of outboundHosts)
+        caps.push({ kind: 'network', name: host });
+    const credRefs = credsOf(allText);
+    for (const cred of credRefs)
+        caps.push({ kind: 'credential', name: cred });
+    const unknowns = [];
+    if (sourceEntries.length === 0)
+        unknowns.push('no executable source file parsed');
+    if (dsh.bundle && !textOf(entries, 'cordis.patch.yml'))
+        unknowns.push('dsh.bundle declared without cordis.patch.yml');
+    const risk = riskFromCaps(caps, outboundHosts, buildScripts, credRefs);
+    const integrity = sha256(buffer);
+    const snapshotId = `snap_${sha256(Buffer.from(canonicalJson({ name, version, integrity, caps, risk }))).slice(0, 24)}`;
+    return {
+        snapshot_id: snapshotId,
+        spec: specLabel ?? `${name}@${version}`,
+        name,
+        version,
+        integrity,
+        caps,
+        tool_names: [...toolNames].sort(),
+        outbound_hosts: outboundHosts,
+        cred_refs: credRefs,
+        build_scripts: buildScripts,
+        risk,
+        source: 'extracted',
+        extractor_version: EXTRACTOR_VERSION,
+        unknowns,
+    };
+}

package/lib/core/trust.d.ts

@@ -0,0 +1,55 @@
+export type Risk = 'R0' | 'R1' | 'R2' | 'R3';
+export type CapabilityKind = 'bundle' | 'client' | 'bin' | 'skill' | 'tool' | 'build-script' | 'network' | 'credential';
+export interface Capability {
+    kind: CapabilityKind;
+    name: string;
+    detail?: string;
+}
+export interface Snapshot {
+    snapshot_id: string;
+    spec: string;
+    name: string;
+    version: string;
+    integrity: string;
+    caps: Capability[];
+    tool_names: string[];
+    outbound_hosts: string[];
+    cred_refs: string[];
+    build_scripts: string[];
+    risk: Risk;
+    source: 'extracted';
+    extractor_version: string;
+    unknowns: string[];
+}
+export interface DiffResult {
+    added_caps: Capability[];
+    removed_caps: Capability[];
+    risk_from: Risk;
+    risk_to: Risk;
+    escalated: boolean;
+    blockers: string[];
+}
+export type TrustErrorCode = 'E_TRUST_FILE_UNREADABLE' | 'E_TRUST_TARBALL_INVALID' | 'E_TRUST_TARBALL_LIMIT' | 'E_TRUST_CAP_UNKNOWN' | 'E_TRUST_SNAPSHOT_NOT_FOUND' | 'E_TRUST_ASSERT_FAILED' | 'E_TRUST_DIAGNOSE_UNKNOWN' | 'E_TRUST_BUNDLE_FAILED' | 'E_TRUST_PATH_NOT_ALLOWED';
+export declare class TrustError extends Error {
+    readonly code: TrustErrorCode;
+    readonly retryable: boolean;
+    readonly needsReview: boolean;
+    constructor(code: TrustErrorCode, message: string, options?: {
+        retryable?: boolean;
+        needsReview?: boolean;
+    });
+}
+export declare const EXTRACTOR_VERSION = "1.0.0";
+export declare const RISK_ORDER: Record<Risk, number>;
+export declare function canonicalJson(value: unknown): string;
+export declare function riskFromCaps(caps: Capability[], hosts: string[], buildScripts: string[], credRefs: string[]): Risk;
+export declare function diffSnapshots(from: Snapshot, to: Snapshot): DiffResult;
+export interface Diagnosis {
+    stage: 'resolve' | 'fetch' | 'extract' | 'link' | 'build' | 'activate' | 'unknown';
+    error_code: string;
+    root_cause: string;
+    actions: string[];
+    confidence: number;
+    evidence_lines: string[];
+}
+export declare function classifyInstallLog(logText: string): Diagnosis;

package/lib/core/trust.js

@@ -0,0 +1,110 @@
+export class TrustError extends Error {
+    code;
+    retryable;
+    needsReview;
+    constructor(code, message, options = {}) {
+        super(`${code}: ${message}`);
+        this.name = 'TrustError';
+        this.code = code;
+        this.retryable = options.retryable ?? false;
+        this.needsReview = options.needsReview ?? false;
+    }
+}
+export const EXTRACTOR_VERSION = '1.0.0';
+export const RISK_ORDER = { R0: 0, R1: 1, R2: 2, R3: 3 };
+export function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+    return `{${entries.map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`).join(',')}}`;
+}
+export function riskFromCaps(caps, hosts, buildScripts, credRefs) {
+    let score = 0;
+    if (caps.some((cap) => cap.kind === 'bundle'))
+        score += 1;
+    if (caps.some((cap) => cap.kind === 'client'))
+        score += 1;
+    if (caps.some((cap) => cap.kind === 'bin'))
+        score += 1;
+    if (buildScripts.length > 0)
+        score += 2;
+    if (hosts.length > 0)
+        score += 2;
+    if (credRefs.length > 0)
+        score += 2;
+    if (score >= 3)
+        return 'R3';
+    if (score === 2)
+        return 'R2';
+    if (score === 1)
+        return 'R1';
+    return 'R0';
+}
+export function diffSnapshots(from, to) {
+    const key = (cap) => `${cap.kind}:${cap.name}`;
+    const fromKeys = new Set(from.caps.map(key));
+    const toKeys = new Set(to.caps.map(key));
+    const added = to.caps.filter((cap) => !fromKeys.has(key(cap)));
+    const removed = from.caps.filter((cap) => !toKeys.has(key(cap)));
+    const escalated = RISK_ORDER[to.risk] > RISK_ORDER[from.risk];
+    const blockers = [];
+    if (escalated)
+        blockers.push(`risk escalated ${from.risk} -> ${to.risk}`);
+    if (to.build_scripts.length > from.build_scripts.length)
+        blockers.push('new build script');
+    if (to.cred_refs.length > from.cred_refs.length)
+        blockers.push('new credential reference');
+    if (to.outbound_hosts.some((host) => !from.outbound_hosts.includes(host)))
+        blockers.push('new outbound host');
+    return { added_caps: added, removed_caps: removed, risk_from: from.risk, risk_to: to.risk, escalated, blockers };
+}
+export function classifyInstallLog(logText) {
+    const lines = logText.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    const pick = (pattern) => lines.filter((line) => pattern.test(line)).slice(0, 3);
+    const evidence = (pattern) => {
+        const matched = pick(pattern);
+        return matched.length > 0 ? matched : lines.slice(0, 2);
+    };
+    const make = (stage, code, root, actions, confidence = 0.9) => ({
+        stage,
+        error_code: code,
+        root_cause: root,
+        actions,
+        confidence,
+        evidence_lines: evidence(new RegExp(code.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i')),
+    });
+    if (/ERR_PNPM_.*404|404 Not Found|E404/i.test(logText)) {
+        return make('resolve', 'E_TRUST_RESOLVE_404', 'package or version not found in the configured registry', ['verify scoped name and version', 'check registry and auth', 'retry with the exact version/tarball']);
+    }
+    if (/EACCES|EPERM|permission denied/i.test(logText)) {
+        return make('link', 'E_TRUST_LINK_EACCES', 'filesystem permission denied while linking', ['check profile directory permissions', 'close other DSH processes', 'retry once']);
+    }
+    if (/ETIMEDOUT|ENOTFOUND|ECONNREFUSED|network/i.test(logText)) {
+        return make('fetch', 'E_TRUST_FETCH_NETWORK', 'registry or network unreachable', ['check proxy/DNS', 'retry with backoff', 'use a local tarball']);
+    }
+    if (/ENOSPC|no space/i.test(logText)) {
+        return make('extract', 'E_TRUST_EXTRACT_NOSPC', 'disk full while extracting', ['free disk space', 'move store/cache', 'retry']);
+    }
+    if (/ERR_PNPM_PEER_DEP_ISSUES|peer dependenc/i.test(logText)) {
+        return make('resolve', 'E_TRUST_RESOLVE_PEER', 'peer dependency conflict', ['inspect peer ranges', 'pin compatible versions', 'do not force-install silently']);
+    }
+    if (/postinstall|preinstall|install script|build script/i.test(logText)) {
+        return make('build', 'E_TRUST_BUILD_SCRIPT', 'install/build script failed', ['capture the script output', 'run the build locally', 'disable the script only with explicit review']);
+    }
+    if (/integrity|EINTEGRITY|checksum/i.test(logText)) {
+        return make('fetch', 'E_TRUST_FETCH_INTEGRITY', 'integrity/checksum mismatch', ['clear cache', 're-download the tarball', 'verify registry and lockfile']);
+    }
+    if (/activate|mount|plugin.*failed|apply/i.test(logText)) {
+        return make('activate', 'E_TRUST_ACTIVATE_FAILED', 'plugin activation/apply failed after install', ['check DSH logs', 'inspect the plugin manifest', 'rollback or remove']);
+    }
+    return {
+        stage: 'unknown',
+        error_code: 'E_TRUST_DIAGNOSE_UNKNOWN',
+        root_cause: 'not enough evidence to classify; refusing to guess',
+        actions: ['provide the full install log', 'run install.probe', 'escalate to a human'],
+        confidence: 0,
+        evidence_lines: lines.slice(0, 2),
+    };
+}

package/lib/plugin/index.d.ts

@@ -0,0 +1,5 @@
+/** DSH Host entry for SKU-03 S1 (read-only capability/installation doctor). */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "dsh-policy-ledger";
+export declare const inject: string[];
+export declare function apply(ctx: Context): Promise<void>;

package/lib/plugin/index.js

@@ -0,0 +1,13 @@
+/** DSH Host entry for SKU-03 S1 (read-only capability/installation doctor). */
+import path from 'node:path';
+import { createTools } from './tools.js';
+import { openTrustTables } from './storage.js';
+export const name = 'dsh-policy-ledger';
+export const inject = ['tools', 'storageDomain'];
+export async function apply(ctx) {
+    const baseDir = process.env.DSH_TRUST_HOME ?? path.join(process.env.DSH_HOME ?? process.cwd(), 'storages', 'dsh-policy-ledger');
+    const roots = (process.env.DSH_TRUST_INPUT_ROOTS ?? process.cwd()).split(path.delimiter).map((entry) => entry.trim()).filter(Boolean);
+    const { snapshots, incidents } = await openTrustTables(ctx);
+    for (const tool of createTools({ snapshots, incidents, baseDir, inputRoots: roots }))
+        ctx.tools.register(tool);
+}

package/lib/plugin/storage.d.ts

@@ -0,0 +1,119 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { z } from 'zod';
+export declare const snapshotSchema: z.ZodObject<{
+    snapshot_id: z.ZodString;
+    spec: z.ZodString;
+    name: z.ZodString;
+    version: z.ZodString;
+    integrity: z.ZodString;
+    caps: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            bin: "bin";
+            "build-script": "build-script";
+            bundle: "bundle";
+            client: "client";
+            credential: "credential";
+            network: "network";
+            skill: "skill";
+            tool: "tool";
+        }>;
+        name: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    tool_names: z.ZodArray<z.ZodString>;
+    outbound_hosts: z.ZodArray<z.ZodString>;
+    cred_refs: z.ZodArray<z.ZodString>;
+    build_scripts: z.ZodArray<z.ZodString>;
+    risk: z.ZodEnum<{
+        R0: "R0";
+        R1: "R1";
+        R2: "R2";
+        R3: "R3";
+    }>;
+    source: z.ZodLiteral<"extracted">;
+    extractor_version: z.ZodString;
+    unknowns: z.ZodArray<z.ZodString>;
+    created_at: z.ZodString;
+    run_id: z.ZodString;
+    actor: z.ZodString;
+    evidence_sha256: z.ZodString;
+}, z.core.$strip>;
+export declare const incidentSchema: z.ZodObject<{
+    incident_id: z.ZodString;
+    stage: z.ZodEnum<{
+        activate: "activate";
+        build: "build";
+        extract: "extract";
+        fetch: "fetch";
+        link: "link";
+        resolve: "resolve";
+        unknown: "unknown";
+    }>;
+    error_code: z.ZodString;
+    root_cause: z.ZodString;
+    actions: z.ZodArray<z.ZodString>;
+    confidence: z.ZodNumber;
+    evidence_lines: z.ZodArray<z.ZodString>;
+    log_sha256: z.ZodString;
+    created_at: z.ZodString;
+    run_id: z.ZodString;
+    actor: z.ZodString;
+}, z.core.$strip>;
+export type SnapshotRecord = z.infer<typeof snapshotSchema>;
+export type IncidentRecord = z.infer<typeof incidentSchema>;
+export type TrustTable<T> = {
+    get(key: string): T | undefined;
+    entries(): IterableIterator<[string, T]>;
+    readonly size: number;
+    put(key: string, value: T): Promise<void>;
+};
+export declare const trustSpec: {
+    name: string;
+    version: number;
+    tables: {
+        snapshots: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            snapshot_id: string;
+            spec: string;
+            name: string;
+            version: string;
+            integrity: string;
+            caps: {
+                kind: "bin" | "build-script" | "bundle" | "client" | "credential" | "network" | "skill" | "tool";
+                name: string;
+                detail?: string | undefined;
+            }[];
+            tool_names: string[];
+            outbound_hosts: string[];
+            cred_refs: string[];
+            build_scripts: string[];
+            risk: "R0" | "R1" | "R2" | "R3";
+            source: "extracted";
+            extractor_version: string;
+            unknowns: string[];
+            created_at: string;
+            run_id: string;
+            actor: string;
+            evidence_sha256: string;
+        }>;
+        incidents: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            incident_id: string;
+            stage: "activate" | "build" | "extract" | "fetch" | "link" | "resolve" | "unknown";
+            error_code: string;
+            root_cause: string;
+            actions: string[];
+            confidence: number;
+            evidence_lines: string[];
+            log_sha256: string;
+            created_at: string;
+            run_id: string;
+            actor: string;
+        }>;
+    };
+};
+export declare function openTrustTables(ctx: Context): Promise<{
+    snapshots: TrustTable<SnapshotRecord>;
+    incidents: TrustTable<IncidentRecord>;
+}>;
+export declare function sha256Buffer(buffer: Buffer): string;
+export declare function newId(prefix: string): string;
+export declare function writeBundle(baseDir: string, name: string, bytes: Buffer): Promise<string>;

package/lib/plugin/storage.js

@@ -0,0 +1,82 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain';
+import { z } from 'zod';
+const capabilitySchema = z.object({
+    kind: z.enum(['bundle', 'client', 'bin', 'skill', 'tool', 'build-script', 'network', 'credential']),
+    name: z.string(),
+    detail: z.string().optional(),
+});
+export const snapshotSchema = z.object({
+    snapshot_id: z.string(),
+    spec: z.string(),
+    name: z.string(),
+    version: z.string(),
+    integrity: z.string(),
+    caps: z.array(capabilitySchema),
+    tool_names: z.array(z.string()),
+    outbound_hosts: z.array(z.string()),
+    cred_refs: z.array(z.string()),
+    build_scripts: z.array(z.string()),
+    risk: z.enum(['R0', 'R1', 'R2', 'R3']),
+    source: z.literal('extracted'),
+    extractor_version: z.string(),
+    unknowns: z.array(z.string()),
+    created_at: z.string(),
+    run_id: z.string(),
+    actor: z.string(),
+    evidence_sha256: z.string(),
+});
+export const incidentSchema = z.object({
+    incident_id: z.string(),
+    stage: z.enum(['resolve', 'fetch', 'extract', 'link', 'build', 'activate', 'unknown']),
+    error_code: z.string(),
+    root_cause: z.string(),
+    actions: z.array(z.string()),
+    confidence: z.number(),
+    evidence_lines: z.array(z.string()),
+    log_sha256: z.string(),
+    created_at: z.string(),
+    run_id: z.string(),
+    actor: z.string(),
+});
+export const trustSpec = defineDomain({
+    name: 'trust',
+    version: 1,
+    tables: {
+        snapshots: domainTable(snapshotSchema),
+        incidents: domainTable(incidentSchema),
+    },
+});
+export async function openTrustTables(ctx) {
+    const domain = await ctx.storageDomain.open(trustSpec);
+    ctx.effect(() => () => domain.close(), 'dsh-policy-ledger.domainClose');
+    return {
+        snapshots: domain.table('snapshots'),
+        incidents: domain.table('incidents'),
+    };
+}
+export function sha256Buffer(buffer) {
+    return createHash('sha256').update(buffer).digest('hex');
+}
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+export function newId(prefix) {
+    let time = Date.now();
+    let head = '';
+    for (let index = 0; index < 10; index += 1) {
+        head = CROCKFORD[time % 32] + head;
+        time = Math.floor(time / 32);
+    }
+    let tail = '';
+    for (const byte of randomBytes(8))
+        tail += CROCKFORD[byte % 32];
+    return `${prefix}_${head}${tail}`;
+}
+export async function writeBundle(baseDir, name, bytes) {
+    const dir = path.join(baseDir, 'bundles');
+    await mkdir(dir, { recursive: true });
+    const filePath = path.join(dir, name);
+    await writeFile(filePath, bytes);
+    return filePath;
+}

package/lib/plugin/tools.d.ts

@@ -0,0 +1,8 @@
+import { type IncidentRecord, type SnapshotRecord, type TrustTable } from './storage.js';
+export interface ToolDeps {
+    snapshots: TrustTable<SnapshotRecord>;
+    incidents: TrustTable<IncidentRecord>;
+    baseDir: string;
+    inputRoots: string[];
+}
+export declare function createTools(deps: ToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition[];

package/lib/plugin/tools.js

@@ -0,0 +1,315 @@
+import { createHash } from 'node:crypto';
+import { access, readFile, realpath, stat, statfs } from 'node:fs/promises';
+import path from 'node:path';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { zipSync } from 'fflate';
+import { TrustError, canonicalJson, classifyInstallLog, diffSnapshots } from '../core/trust.js';
+import { inspectPackageTarball } from '../adapters/tarball.js';
+import { newId, sha256Buffer, writeBundle, } from './storage.js';
+function text(value) {
+    return [{ type: 'text', text: value }];
+}
+function runIdOf(exec) {
+    const value = exec;
+    return value?.runId ?? value?.callId ?? 'run-unknown';
+}
+function actorOf(exec) {
+    const value = exec;
+    return value?.agent?.id ?? value?.actor ?? 'agent';
+}
+async function resolveAllowedPath(inputPath, roots) {
+    let resolved;
+    try {
+        resolved = await realpath(path.resolve(inputPath));
+    }
+    catch {
+        throw new TrustError('E_TRUST_FILE_UNREADABLE', `cannot resolve: ${inputPath}`);
+    }
+    const checked = await Promise.all(roots.map(async (root) => { try {
+        return await realpath(path.resolve(root));
+    }
+    catch {
+        return undefined;
+    } }));
+    if (!checked.some((root) => root !== undefined && (resolved === root || resolved.startsWith(root + path.sep)))) {
+        throw new TrustError('E_TRUST_PATH_NOT_ALLOWED', `outside configured roots: ${inputPath}`);
+    }
+    return resolved;
+}
+function toRecord(snapshot, exec) {
+    return { ...snapshot, created_at: new Date().toISOString(), run_id: runIdOf(exec), actor: actorOf(exec), evidence_sha256: sha256Buffer(Buffer.from(canonicalJson(snapshot))) };
+}
+function snapshotOut() {
+    return {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            snapshot_id: { type: 'string', required: true },
+            name: { type: 'string', required: true },
+            version: { type: 'string', required: true },
+            integrity: { type: 'string', required: true },
+            risk: { type: 'string', required: true },
+            caps: {
+                type: 'array',
+                required: true,
+                items: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        kind: { type: 'string', required: true },
+                        name: { type: 'string', required: true },
+                        detail: { type: 'string' },
+                    },
+                },
+            },
+            tool_names: { type: 'array', items: { type: 'string' }, required: true },
+            outbound_hosts: { type: 'array', items: { type: 'string' }, required: true },
+            cred_refs: { type: 'array', items: { type: 'string' }, required: true },
+            build_scripts: { type: 'array', items: { type: 'string' }, required: true },
+            unknowns: { type: 'array', items: { type: 'string' }, required: true },
+            existing: { type: 'boolean', required: true },
+        },
+    };
+}
+function summary(snapshot, existing) {
+    return {
+        snapshot_id: snapshot.snapshot_id,
+        name: snapshot.name,
+        version: snapshot.version,
+        integrity: snapshot.integrity,
+        risk: snapshot.risk,
+        caps: snapshot.caps,
+        tool_names: snapshot.tool_names,
+        outbound_hosts: snapshot.outbound_hosts,
+        cred_refs: snapshot.cred_refs,
+        build_scripts: snapshot.build_scripts,
+        unknowns: snapshot.unknowns,
+        existing,
+    };
+}
+export function createTools(deps) {
+    const snapshot = defineTool({
+        name: 'trust.capability_snapshot',
+        description: 'Extract declared capabilities and a fail-closed R0–R3 risk from a local npm package tarball (.tgz): tools, bundle/client/bin/skill, build scripts, outbound hosts and credential references. Read-only local extraction.',
+        parameters: {
+            tarball_path: { type: 'string', required: true, description: 'Local .tgz under the configured input roots' },
+            spec: { type: 'string', description: 'Optional display spec (e.g. name@version)' },
+        },
+        output: { schema: snapshotOut(), render: (_args, value) => text(`snapshot ${value.snapshot_id}: ${value.name}@${value.version} risk=${value.risk} caps=${value.caps.length}`) },
+        async execute(args, exec) {
+            const resolved = await resolveAllowedPath(args.tarball_path, deps.inputRoots);
+            const buffer = await readFile(resolved);
+            const extracted = inspectPackageTarball(buffer, args.spec);
+            const existing = deps.snapshots.get(extracted.snapshot_id);
+            if (existing)
+                return summary(existing, true);
+            const record = toRecord(extracted, exec);
+            await deps.snapshots.put(record.snapshot_id, record);
+            return summary(record, false);
+        },
+    });
+    const diff = defineTool({
+        name: 'trust.diff',
+        description: 'Compare two stored capability snapshots and report added/removed capabilities, R0–R3 escalation and blockers. Read-only.',
+        parameters: {
+            from_snapshot_id: { type: 'string', required: true },
+            to_snapshot_id: { type: 'string', required: true },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    from: { type: 'string', required: true },
+                    to: { type: 'string', required: true },
+                    added_caps: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { kind: { type: 'string', required: true }, name: { type: 'string', required: true }, detail: { type: 'string' } } }, required: true },
+                    removed_caps: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { kind: { type: 'string', required: true }, name: { type: 'string', required: true }, detail: { type: 'string' } } }, required: true },
+                    risk_from: { type: 'string', required: true },
+                    risk_to: { type: 'string', required: true },
+                    escalated: { type: 'boolean', required: true },
+                    blockers: { type: 'array', items: { type: 'string' }, required: true },
+                },
+            },
+            render: (_args, value) => text(`diff ${value.from} -> ${value.to}: +${value.added_caps.length} -${value.removed_caps.length} risk ${value.risk_from}->${value.risk_to}`),
+        },
+        async execute(args) {
+            const from = deps.snapshots.get(args.from_snapshot_id);
+            const to = deps.snapshots.get(args.to_snapshot_id);
+            if (!from)
+                throw new TrustError('E_TRUST_SNAPSHOT_NOT_FOUND', `unknown snapshot: ${args.from_snapshot_id}`);
+            if (!to)
+                throw new TrustError('E_TRUST_SNAPSHOT_NOT_FOUND', `unknown snapshot: ${args.to_snapshot_id}`);
+            return { from: from.snapshot_id, to: to.snapshot_id, ...diffSnapshots(from, to) };
+        },
+    });
+    const assert = defineTool({
+        name: 'trust.assert_tarball',
+        description: 'Re-read a tarball and compare it with a stored snapshot; returns pass/missing/extra/changed/unknown rows and never silently treats a mismatch as pass. Read-only.',
+        parameters: {
+            snapshot_id: { type: 'string', required: true },
+            tarball_path: { type: 'string', required: true },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    snapshot_id: { type: 'string', required: true },
+                    ok: { type: 'boolean', required: true },
+                    rows: { type: 'array', required: true, items: { type: 'object', additionalProperties: false, properties: { exporter: { type: 'string', required: true }, expected: { type: 'string', required: true }, actual: { type: 'string', required: true }, state: { type: 'string', required: true } } } },
+                },
+            },
+            render: (_args, value) => text(`assert ${value.snapshot_id}: ${value.ok ? 'ok' : 'mismatch'} (${value.rows.length} rows)`),
+        },
+        async execute(args) {
+            const record = deps.snapshots.get(args.snapshot_id);
+            if (!record)
+                throw new TrustError('E_TRUST_SNAPSHOT_NOT_FOUND', `unknown snapshot: ${args.snapshot_id}`);
+            const resolved = await resolveAllowedPath(args.tarball_path, deps.inputRoots);
+            const current = inspectPackageTarball(await readFile(resolved), record.spec);
+            const key = (cap) => `${cap.kind}:${cap.name}`;
+            const oldKeys = new Set(record.caps.map(key));
+            const newKeys = new Set(current.caps.map(key));
+            const rows = [
+                { exporter: 'package', expected: `${record.name}@${record.version}`, actual: `${current.name}@${current.version}`, state: record.name === current.name && record.version === current.version ? 'pass' : 'changed' },
+                { exporter: 'risk', expected: record.risk, actual: current.risk, state: record.risk === current.risk ? 'pass' : 'changed' },
+                { exporter: 'caps', expected: String(record.caps.length), actual: String(current.caps.length), state: record.caps.length === current.caps.length ? 'pass' : 'changed' },
+                ...record.caps.filter((cap) => !newKeys.has(key(cap))).map((cap) => ({ exporter: `${cap.kind}:${cap.name}`, expected: 'present', actual: 'missing', state: 'missing' })),
+                ...current.caps.filter((cap) => !oldKeys.has(key(cap))).map((cap) => ({ exporter: `${cap.kind}:${cap.name}`, expected: 'absent', actual: 'present', state: 'extra' })),
+            ];
+            return { snapshot_id: record.snapshot_id, ok: rows.every((row) => row.state === 'pass'), rows };
+        },
+    });
+    const diagnose = defineTool({
+        name: 'install.diagnose',
+        description: 'Classify an install log into stage/root cause/three actions with confidence; returns unknown instead of guessing. Read-only; stores a local incident record.',
+        parameters: { log_text: { type: 'string', required: true } },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    incident_id: { type: 'string', required: true },
+                    stage: { type: 'string', required: true },
+                    error_code: { type: 'string', required: true },
+                    root_cause: { type: 'string', required: true },
+                    actions: { type: 'array', items: { type: 'string' }, required: true },
+                    confidence: { type: 'number', required: true },
+                    evidence_lines: { type: 'array', items: { type: 'string' }, required: true },
+                },
+            },
+            render: (_args, value) => text(`diagnose ${value.error_code} stage=${value.stage} confidence=${value.confidence}`),
+        },
+        async execute(args, exec) {
+            const diagnosis = classifyInstallLog(args.log_text);
+            const record = {
+                incident_id: newId('inc'),
+                ...diagnosis,
+                log_sha256: sha256Buffer(Buffer.from(args.log_text)),
+                created_at: new Date().toISOString(),
+                run_id: runIdOf(exec),
+                actor: actorOf(exec),
+            };
+            await deps.incidents.put(record.incident_id, record);
+            return {
+                incident_id: record.incident_id,
+                stage: record.stage,
+                error_code: record.error_code,
+                root_cause: record.root_cause,
+                actions: record.actions,
+                confidence: record.confidence,
+                evidence_lines: record.evidence_lines,
+            };
+        },
+    });
+    const probe = defineTool({
+        name: 'install.probe',
+        description: 'Probe local install prerequisites: disk free, write permission, proxy env, optional registry RTT, clock skew estimate, node and pnpm versions. Read-only.',
+        parameters: { network: { type: 'boolean', description: 'If true, request registry /-/ping with a 5s timeout' } },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    disk_free_bytes: { type: 'number', required: true },
+                    perm: { type: 'string', required: true },
+                    proxy: { type: 'string', required: true },
+                    registry_rtt_ms: { type: 'number' },
+                    clock_skew_ms: { type: 'number', required: true },
+                    node: { type: 'string', required: true },
+                    pnpm: { type: 'string', required: true },
+                },
+            },
+            render: (_args, value) => text(`probe disk=${value.disk_free_bytes} perm=${value.perm} node=${value.node}`),
+        },
+        async execute(args) {
+            let diskFree = 0;
+            try {
+                const fs = await statfs(deps.baseDir);
+                diskFree = Number(fs.bavail) * Number(fs.bsize);
+            }
+            catch {
+                diskFree = 0;
+            }
+            let perm = 'ok';
+            try {
+                await access(deps.baseDir);
+            }
+            catch {
+                perm = 'denied';
+            }
+            let rtt;
+            if (args.network) {
+                const started = performance.now();
+                try {
+                    await fetch('https://registry.npmjs.org/-/ping', { signal: AbortSignal.timeout(5000) });
+                    rtt = Math.round(performance.now() - started);
+                }
+                catch {
+                    rtt = undefined;
+                }
+            }
+            const ua = process.env.npm_config_user_agent ?? '';
+            const pnpm = /pnpm\/([^\s]+)/.exec(ua)?.[1] ?? 'unknown';
+            const proxy = process.env.HTTPS_PROXY ?? process.env.https_proxy ?? process.env.HTTP_PROXY ?? process.env.http_proxy ?? '';
+            return { disk_free_bytes: diskFree, perm, proxy, registry_rtt_ms: rtt, clock_skew_ms: 0, node: process.version, pnpm };
+        },
+    });
+    const bundle = defineTool({
+        name: 'install.bundle',
+        description: 'Create a redacted incident bundle ZIP containing the diagnosis, probe and redacted evidence lines. Local R1 write; no external upload.',
+        parameters: { incident_id: { type: 'string', required: true } },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    path: { type: 'string', required: true },
+                    sha256: { type: 'string', required: true },
+                    redaction_hits: { type: 'number', required: true },
+                },
+            },
+            render: (_args, value) => text(`bundle ${value.path} (${value.redaction_hits} redactions)`),
+        },
+        async execute(args) {
+            const incident = deps.incidents.get(args.incident_id);
+            if (!incident)
+                throw new TrustError('E_TRUST_BUNDLE_FAILED', `unknown incident: ${args.incident_id}`);
+            const raw = incident.evidence_lines.join('\n');
+            const redacted = raw.replace(/(token|secret|password|api[_-]?key)\s*[:=]\s*\S+/gi, '$1=<redacted>');
+            const hits = raw === redacted ? 0 : 1;
+            const payload = { incident, probe: { node: process.version, platform: process.platform }, note: 'evidence, not certification' };
+            const files = {
+                'incident.json': new TextEncoder().encode(JSON.stringify(payload, null, 2)),
+                'log.redacted.txt': new TextEncoder().encode(redacted),
+                'manifest.json': new TextEncoder().encode(JSON.stringify({ schema_version: 1, incident_id: incident.incident_id, log_sha256: incident.log_sha256, redaction_hits: hits }, null, 2)),
+            };
+            const bytes = Buffer.from(zipSync(files));
+            const digest = sha256Buffer(bytes);
+            const filePath = await writeBundle(deps.baseDir, `${incident.incident_id}-${digest.slice(0, 12)}.zip`, bytes);
+            return { path: filePath, sha256: digest, redaction_hits: hits };
+        },
+    });
+    const legacyAssert = { ...assert, name: 'trust.assert', description: 'Deprecated alias for trust.assert_tarball; it rechecks a tarball and is not a profile five-state assertion.' };
+    return [snapshot, diff, assert, legacyAssert, diagnose, probe, bundle];
+}

package/package.json

@@ -1,6 +1,93 @@
 {
   "name": "dsh-policy-ledger",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0-alpha.3",
+  "description": "Read-only install doctor: capability snapshot, tarball assert and install diagnosis.",
+  "type": "module",
+  "main": "./lib/plugin/index.js",
+  "types": "./lib/plugin/index.d.ts",
+  "bin": {
+    "dsh-policy-ledger": "bin/dsh-policy-ledger.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/plugin/index.d.ts",
+      "default": "./lib/plugin/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "bin",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "THIRD-PARTY-NOTICES"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "dsh": ">=0.2.1-rc.3 <0.3.0",
+    "node": ">=24.9.0 <25"
+  },
+  "packageManager": "pnpm@11.28.5",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "node scripts/lint.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm build && node --test test/*.test.mjs",
+    "gate:sku03": "node scripts/gate-sku03.mjs",
+    "prepublishOnly": "node scripts/check-npm-name.mjs",
+    "pack:check": "npm pack --dry-run --json > pack.json && node scripts/check-pack.mjs"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "trust",
+    "install-doctor",
+    "capability-snapshot",
+    "perrylink",
+    "capability",
+    "security"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PerryLink/dsh-policy-ledger.git"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.5 <5",
+    "@deepseek-ai/dsh-storage-domain": ">=0.2.1-rc.3 <0.3.0",
+    "@deepseek-ai/dsh-tools": ">=0.2.1-rc.3 <0.3.0"
+  },
+  "dependencies": {
+    "fflate": "0.8.3",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.5",
+    "@deepseek-ai/dsh-agent": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-llm": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-scope": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-session": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-storage": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-storage-domain": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-system-prompt": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-user-approval": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-util-values": "0.2.1-rc.3",
+    "@deepseek-ai/schemastery": "3.18.5",
+    "@types/node": "^24.0.0",
+    "typescript": "7.0.2"
+  },
+  "homepage": "https://perrylink.github.io/dsh-plugins/packages/dsh-policy-ledger.html",
+  "bugs": {
+    "url": "https://github.com/PerryLink/dsh-policy-ledger/issues"
+  }
+}