@aikdna/kdna-core 0.11.1 → 0.12.0

package/README.md

@@ -1,6 +1,10 @@
 # @aikdna/kdna-core
 
-Core library for loading, validating, linting, rendering, composing, and directly reading KDNA `.kdna` cognition assets. It has zero npm runtime dependencies.
+Core library for KDNA judgment assets.
+
+KDNA Core v1 defines the official `.kdna` source/container contract used by
+the CLI, Studio export, skills, MCP integrations, and downstream agent
+runtimes.
 
 ## Installation
 
@@ -8,187 +12,92 @@ Core library for loading, validating, linting, rendering, composing, and directl
 npm install @aikdna/kdna-core
 ```
 
-## Preferred public API
-
-Third-party adapters should start with the stable asset-first API. These
-functions accept a `.kdna` file path, bytes, or an already opened asset and do
-not require persistent extraction.
+If you need full JSON Schema validation through Ajv, also install:
 
-```js
-const {
-  inspectKDNA,
-  validateKDNA,
-  loadKDNA,
-  renderForAgent,
-  verifyAsset,
-  verifyDigest,
-  verifySignature,
-  matchDomain,
-  composeKDNA
-} = require('@aikdna/kdna-core');
-
-const info = await inspectKDNA('./writing.kdna');
-const validation = await validateKDNA('./writing.kdna');
-const loaded = await loadKDNA('./writing.kdna', { profile: 'compact' });
-const promptContext = await renderForAgent('./writing.kdna');
-
-await verifyAsset('./writing.kdna', {
-  asset_digest: info.asset_digest,
-  requireSignature: true
-});
-await verifyDigest('./writing.kdna', info.asset_digest);
-await verifySignature('./writing.kdna');
-
-const matches = await matchDomain('Review this writing draft', ['./writing.kdna']);
-const composed = await composeKDNA(['./writing.kdna', './agent_safety.kdna'], {
-  input: 'Review this public release note for safety and writing quality'
-});
+```bash
+npm install ajv ajv-formats
 ```
 
-Stable entry points:
-
-| Function | Purpose |
-| --- | --- |
-| `openKDNA()` | Open a `.kdna` file or bytes as an immutable asset. |
-| `inspectKDNA()` | Return manifest, entries, access, quality, risk, and digests. |
-| `validateKDNA()` | Run asset, lint, schema, and cross-file validation. |
-| `loadKDNA()` | Load index/compact/scenario/full profiles directly from `.kdna`. |
-| `renderForAgent()` | Render a loaded asset into agent prompt context. |
-| `verifyAsset()` | Run full asset verification: digest, content digest, signature, and trust metadata. |
-| `verifyDigest()` | Check whole-file `asset_digest`. |
-| `verifySignature()` | Require Ed25519 signature verification. |
-| `matchDomain()` | Rank candidate assets for a task string. |
-| `composeKDNA()` | Compose multiple assets with attribution and conflict reporting. |
+## KDNA Core v1 API
 
-## Lower-level usage
+Use the `./v1` entrypoint for current KDNA Core v1 tooling:
 
 ```js
 const {
-  createKdnaAssetReader,
-  lintDomain,
-  validateDomainSchema,
-  validateCrossFile
-} = require('@aikdna/kdna-core');
-
-// Validate a domain
-const dataMap = {
-  'KDNA_Core.json': { meta: { domain: 'my_domain' }, axioms: [...] },
-  'KDNA_Patterns.json': { meta: { domain: 'my_domain' }, self_check: [...] }
-};
-
-const lintResult = lintDomain(dataMap);
-const schemaResult = validateDomainSchema(dataMap, schemas);
-const crossResult = validateCrossFile(dataMap);
-```
-
-## API
-
-### `createKdnaAssetReader()`
-
-Direct `.kdna` container reader. The reader opens ZIP-backed `.kdna` assets without persistent extraction and exposes:
-
-- `open(pathOrBytes)`
-- `listEntries(asset)`
-- `readEntry(asset, entryName)`
-- `readJson(asset, entryName)`
-- `readManifest(asset)`
-- `readDataMap(asset)`
-- `contentDigest(asset)`
-- `verify(asset, { asset_digest?, content_digest?, requireSignature? })`
-- `loadProfile(asset, "index" | "compact" | "scenario" | "full", options?)`
-
-Example:
-
-```js
-const { createKdnaAssetReader } = require('@aikdna/kdna-core');
-
-const reader = createKdnaAssetReader();
-const asset = await reader.open('./writing.kdna');
-const manifest = await reader.readManifest(asset);
-const trust = await reader.verify(asset, { requireSignature: true });
-const loaded = await reader.loadProfile(asset, 'compact');
-```
-
-The asset reader treats extraction caches as implementation details. The `.kdna` file remains the identity, install, verification, and loading object.
-
-Licensed assets can list encrypted JSON entries in `kdna.json`:
-
-```json
-{
-  "access": "licensed",
-  "encryption": {
-    "profile": "kdna-licensed-entry-v1",
-    "encrypted_entries": ["KDNA_Core.json", "KDNA_Patterns.json"]
-  }
+  inspect,
+  validate,
+  pack,
+  unpack,
+  loadV1,
+  buildChecksumsV1
+} = require('@aikdna/kdna-core/v1');
+
+const validation = validate('./asset.kdna');
+if (!validation.overall_valid) {
+  throw new Error(validation.problems.join('\n'));
 }
-```
-
-The reader never writes decrypted entries to disk. Callers provide an in-memory
-`decryptEntry` hook when they have already validated license activation:
-
-```js
-const { createLicensedDecryptEntry } = require('@aikdna/kdna-core');
 
-const decryptEntry = createLicensedDecryptEntry({
-  licenseKey: activation.license_key,
-  machineFingerprint: activation.machine_fingerprint
+const compact = loadV1('./asset.kdna', {
+  profile: 'compact',
+  as: 'prompt'
 });
-
-const loaded = await reader.loadProfile(asset, 'compact', { decryptEntry });
 ```
 
-The profile uses AES-256-GCM over each protected entry and derives the entry key
-from the license key plus machine fingerprint using `scrypt-sha256`. This is a
-runtime primitive, not a license activation system; callers must validate license
-status before passing a decrypt hook to the reader.
-
-### `lintDomain(dataMap)`
-Structural linting — checks required files, field presence, unique IDs, yes/no answerable self-checks, cross-file references, and flags potentially vague axioms.
-
-Returns `{ errors: string[], warnings: string[] }`.
-
-### `validateDomainSchema(dataMap, schemaMap)`
-JSON Schema validation against published schemas (KDNA_Core, KDNA_Patterns, KDNA_Scenarios, KDNA_Cases, KDNA_Reasoning, KDNA_Evolution).
+## Supported Runtime Flow
 
-Returns `{ errors: string[], warnings: string[] }`.
-
-### `validateCrossFile(dataMap)`
-Cross-file consistency checks — ensures references between domain files are valid.
-
-Returns `{ errors: string[], warnings: string[] }`.
-
-### `renderDomain(dataMap, options?)`
-Renders domain files into a structured context block using a standard template. The rendered context preserves the domain's structure as distinct, named sections suitable for agent system prompts.
+```text
+v1 source directory
+→ buildChecksumsV1
+→ pack
+→ validate
+→ loadV1
+→ agent/runtime context
+```
 
-## Compose API (9 functions)
+## v1 Source Directory
 
-Multi-domain composition — load multiple KDNA domains, classify which should activate for a given input, detect conflicts, and merge their judgment into a single agent context.
+A v1 source directory contains:
 
-### Context Composition
+- `mimetype`
+- `kdna.json`
+- `payload.kdnab`
+- `checksums.json`
 
-- **`composeContext(domains, options?)`** — Merge multiple loaded domains into a single context string. Conflicting axioms or banned terms from different domains are both included; the agent must report the conflict rather than silently resolve it.
+## v1 Container
 
-- **`composeContextWithAttribution(domains, options?)`** — Same as `composeContext`, but every axiom, misunderstanding, banned term, and self-check is prefixed with its origin domain (e.g., `[writing:axiom.axiom_problem_not_prose]`). Returns `{ context, attributionMap }`.
+A v1 `.kdna` container is a zip package of the same files. `validate()` checks:
 
-- **`loadAndCompose(dataMaps, options?)`** — Convenience function: loads each domain from file data maps, classifies signals against input, then composes the active domains. Returns `{ domains, context, activeIndices }`.
+- format
+- manifest schema
+- payload parseability
+- checksum consistency
+- load-profile contract
 
-### Signal Classification
+## Load Profiles
 
-- **`classifySignals(input, domains)`** — Match user input against each domain's `trigger_signals`. Returns indices of matching domains. Domains with no signals defined are treated as primary (always active).
+`loadV1()` supports:
 
-- **`classifySignalsAcrossDomains(input, domainEntries)`** — Full diagnostic version of signal classification. Returns `{ selected, excluded }` with reasons (`signal_match`, `required`, `blocked by does_not_apply_when`, `no signal match`).
+- `index`
+- `compact`
+- `scenario`
+- `full`
 
-### Cluster Operations
+Output formats:
 
-- **`loadCluster(clusterManifestPath, domainLoader)`** — Load a cluster manifest (`kdna.cluster.json`) and resolve each domain via the provided loader function. Returns `{ manifest, domains, errors }`.
+- `json`
+- `prompt`
 
-- **`detectDomainConflicts(domains)`** — Detect conflicts between loaded domains in a cluster. Currently checks for: (1) banned term collisions across domains, (2) contradictory stances (simple negation heuristic). Returns array of conflict objects with `type`, `domains`, and `description`.
+## Boundary
 
-- **`generateClusterTrace({ input, loadedDomains, activeDomains, conflicts })`** — Generate a judgment trace record for a cluster operation. Returns `{ input, timestamp, loaded_domains, active_domains, active_count, domains_excluded, conflicts }`.
+KDNA Core v1 is content-neutral. It does not recommend assets, assign quality
+badges, run a marketplace, or define a public registry. Future signature,
+encryption, licensing, and entitlement work is gated outside the current v1
+baseline.
 
-### Utilities
+## Legacy API
 
-- **`composeChecks(domains)`** — Merge self-check items from multiple domains into a single checklist. Each item is prefixed with its domain name so overlaps are visible.
+The package root still exports compatibility APIs for older KDNA paths. New
+tooling should prefer `@aikdna/kdna-core/v1`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-core",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "KDNA core library — load, validate, lint, and render KDNA domain judgment assets. Supports KDNA Container format (payload.kdnab via CBOR).",
   "type": "commonjs",
   "main": "src/index.js",

package/schema/load-plan.schema.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/aikdna/kdna/schema/load-plan.schema.json",
+  "title": "KDNA LoadPlan v1",
+  "description": "Machine-readable pre-load authorization and runtime planning result for KDNA Core v1 assets.",
+  "type": "object",
+  "required": [
+    "kdna_version",
+    "asset",
+    "access",
+    "access_alias",
+    "entitlement_profile",
+    "state",
+    "required_action",
+    "can_load_now",
+    "projection_policy",
+    "checks",
+    "issues",
+    "source"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "kdna_version": { "type": ["string", "null"] },
+    "asset": {
+      "type": "object",
+      "required": ["asset_id", "asset_uid", "title", "version", "judgment_version"],
+      "additionalProperties": false,
+      "properties": {
+        "asset_id": { "type": ["string", "null"] },
+        "asset_uid": { "type": ["string", "null"] },
+        "title": { "type": ["string", "null"] },
+        "version": { "type": ["string", "null"] },
+        "judgment_version": { "type": ["string", "null"] }
+      }
+    },
+    "access": {
+      "type": ["string", "null"],
+      "enum": ["public", "licensed", "remote", null]
+    },
+    "access_alias": { "type": ["string", "null"] },
+    "entitlement_profile": { "type": ["string", "null"] },
+    "state": {
+      "type": "string",
+      "enum": [
+        "ready",
+        "needs_password",
+        "needs_license",
+        "needs_account",
+        "needs_org_auth",
+        "needs_runtime",
+        "offline_grace",
+        "expired",
+        "revoked",
+        "invalid"
+      ]
+    },
+    "required_action": {
+      "type": "string",
+      "enum": [
+        "none",
+        "load",
+        "enter_password",
+        "install_receipt",
+        "sign_in_or_activate",
+        "sync",
+        "connect_runtime",
+        "migrate_legacy",
+        "block"
+      ]
+    },
+    "can_load_now": { "type": "boolean" },
+    "projection_policy": {
+      "type": "string",
+      "enum": ["minimal", "remote", "none"]
+    },
+    "checks": {
+      "type": "object",
+      "required": [
+        "format_valid",
+        "schema_valid",
+        "payload_valid",
+        "checksums_valid",
+        "load_contract_valid",
+        "overall_valid"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "format_valid": { "type": "boolean" },
+        "schema_valid": { "type": "boolean" },
+        "payload_valid": { "type": "boolean" },
+        "checksums_valid": { "type": "boolean" },
+        "load_contract_valid": { "type": "boolean" },
+        "overall_valid": { "type": "boolean" }
+      }
+    },
+    "issues": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["code", "severity", "message"],
+        "additionalProperties": false,
+        "properties": {
+          "code": { "type": "string", "pattern": "^KDNA_[A-Z0-9_]+$" },
+          "severity": { "type": "string", "enum": ["info", "warning", "blocking"] },
+          "message": { "type": "string" }
+        }
+      }
+    },
+    "source": {
+      "type": "object",
+      "required": ["kind", "path"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": { "type": ["string", "null"], "enum": ["dir", "file", null] },
+        "path": { "type": "string" }
+      }
+    }
+  }
+}

package/src/types.d.ts

@@ -507,6 +507,56 @@ export function isV1SourceDir(inputPath: string): boolean;
 export function detectContainerFormat(inputPath: string): 'v1' | 'v2' | null;
 export function inspect(inputPath: string, options?: Record<string, any>): Record<string, any>;
 export function validate(inputPath: string, options?: Record<string, any>): Record<string, any>;
+export interface KDNAV1LoadPlanIssue {
+  code: string;
+  severity: 'info' | 'warning' | 'blocking' | string;
+  message: string;
+}
+export interface KDNAV1LoadPlan {
+  kdna_version: string | null;
+  asset: {
+    asset_id: string | null;
+    asset_uid: string | null;
+    title: string | null;
+    version: string | null;
+    judgment_version: string | null;
+  };
+  access: 'public' | 'licensed' | 'remote' | string | null;
+  access_alias: string | null;
+  entitlement_profile: string | null;
+  state:
+    | 'ready'
+    | 'needs_password'
+    | 'needs_license'
+    | 'needs_account'
+    | 'needs_org_auth'
+    | 'needs_runtime'
+    | 'offline_grace'
+    | 'expired'
+    | 'revoked'
+    | 'invalid'
+    | string;
+  required_action:
+    | 'none'
+    | 'load'
+    | 'enter_password'
+    | 'install_receipt'
+    | 'sign_in_or_activate'
+    | 'sync'
+    | 'connect_runtime'
+    | 'migrate_legacy'
+    | 'block'
+    | string;
+  can_load_now: boolean;
+  projection_policy: 'minimal' | 'remote' | 'none' | string;
+  checks: Record<string, boolean>;
+  issues: KDNAV1LoadPlanIssue[];
+  source: {
+    kind: 'dir' | 'file' | string | null;
+    path: string;
+  };
+}
+export function planLoad(inputPath: string, options?: { password?: string; hasPassword?: boolean; entitlement?: Record<string, any> }): KDNAV1LoadPlan;
 export function buildChecksumsV1(sourceDir: string): KDNAV1Checksums;
 export function pack(sourceDir: string, outputPath: string): void;
 export function unpack(inputPath: string, outputDir: string): void;

package/src/v1/index.js

@@ -750,6 +750,330 @@ function validate(inputPath, opts = {}) {
   return runValidate(v1);
 }
 
+function normalizeAccess(access) {
+  const value = access || 'public';
+  if (value === 'open') return { access: 'public', alias: value };
+  if (value === 'protected') return { access: 'licensed', alias: value };
+  if (value === 'runtime') return { access: 'remote', alias: value };
+  return { access: value, alias: null };
+}
+
+function inferEntitlementProfile(manifest) {
+  if (manifest.entitlement && typeof manifest.entitlement.profile === 'string') {
+    return manifest.entitlement.profile;
+  }
+  if (manifest.encryption && manifest.encryption.profile === 'kdna-password-protected-v1') {
+    return 'password';
+  }
+  if (manifest.access === 'protected') return 'password';
+  return null;
+}
+
+function buildLoadPlanIssue(code, severity, message) {
+  return { code, severity, message };
+}
+
+function validationProblemCode(problem) {
+  if (/checksums?:/i.test(problem)) return 'KDNA_INTEGRITY_DIGEST_FAILED';
+  if (/signature/i.test(problem)) return 'KDNA_INTEGRITY_SIGNATURE_FAILED';
+  if (/payload:/i.test(problem)) return 'KDNA_FORMAT_INVALID';
+  if (/manifest:/i.test(problem)) return 'KDNA_FORMAT_INVALID';
+  if (/load_contract:/i.test(problem)) return 'KDNA_FORMAT_INVALID';
+  return 'KDNA_FORMAT_INVALID';
+}
+
+function finalizeLoadPlan(plan) {
+  assertNoForbiddenTerms(plan);
+  return plan;
+}
+
+function baseLoadPlan(inputPath, v1, validation) {
+  const manifest = v1.manifest;
+  const accessInfo = normalizeAccess(manifest.access);
+  const entitlementProfile = inferEntitlementProfile(manifest);
+  const asset = {
+    asset_id: manifest.asset_id || null,
+    asset_uid: manifest.asset_uid || null,
+    title: manifest.title || null,
+    version: manifest.version || null,
+    judgment_version: manifest.judgment_version || null,
+  };
+
+  const plan = {
+    kdna_version: manifest.kdna_version || null,
+    asset,
+    access: accessInfo.access,
+    access_alias: accessInfo.alias,
+    entitlement_profile: entitlementProfile,
+    state: 'invalid',
+    required_action: 'block',
+    can_load_now: false,
+    projection_policy: 'none',
+    checks: {
+      format_valid: validation.format_valid,
+      schema_valid: validation.schema_valid,
+      payload_valid: validation.payload_valid,
+      checksums_valid: validation.checksums_valid,
+      load_contract_valid: validation.load_contract_valid,
+      overall_valid: validation.overall_valid,
+    },
+    issues: [],
+    source: {
+      kind: v1.kind,
+      path: path.resolve(inputPath),
+    },
+  };
+
+  if (accessInfo.alias) {
+    plan.issues.push(buildLoadPlanIssue(
+      'KDNA_AUTH_ACCESS_ALIAS',
+      'info',
+      `Access value "${accessInfo.alias}" is treated as "${accessInfo.access}".`,
+    ));
+  }
+
+  return plan;
+}
+
+/**
+ * Plan a KDNA v1 runtime load without decrypting or emitting judgment content.
+ * Product consumers such as Chat should render authorization UI from this
+ * result instead of parsing manifest fields directly.
+ */
+function planLoad(inputPath, opts = {}) {
+  let v1;
+  try {
+    v1 = readV1Layout(path.resolve(inputPath));
+  } catch (e) {
+    return finalizeLoadPlan({
+      kdna_version: null,
+      asset: {
+        asset_id: null,
+        asset_uid: null,
+        title: null,
+        version: null,
+        judgment_version: null,
+      },
+      access: null,
+      access_alias: null,
+      entitlement_profile: null,
+      state: 'invalid',
+      required_action: 'block',
+      can_load_now: false,
+      projection_policy: 'none',
+      checks: {
+        format_valid: false,
+        schema_valid: false,
+        payload_valid: false,
+        checksums_valid: false,
+        load_contract_valid: false,
+        overall_valid: false,
+      },
+      issues: [
+        buildLoadPlanIssue('KDNA_FORMAT_INVALID', 'blocking', e.message),
+      ],
+      source: {
+        kind: null,
+        path: path.resolve(inputPath),
+      },
+    });
+  }
+
+  const validation = runValidate(v1);
+  const plan = baseLoadPlan(inputPath, v1, validation);
+
+  if (!validation.overall_valid) {
+    plan.state = 'invalid';
+    plan.required_action = 'block';
+    plan.can_load_now = false;
+    plan.projection_policy = 'none';
+    for (const problem of validation.problems) {
+      plan.issues.push(buildLoadPlanIssue(validationProblemCode(problem), 'blocking', problem));
+    }
+    return finalizeLoadPlan(plan);
+  }
+
+  const manifest = v1.manifest;
+  const payloadDeclaredEncrypted =
+    manifest.payload && manifest.payload.encrypted === true;
+  const encryptedEntries = Array.isArray(manifest.encryption && manifest.encryption.encrypted_entries)
+    ? manifest.encryption.encrypted_entries
+    : [];
+  const hasEncryptedPayload = payloadDeclaredEncrypted || encryptedEntries.length > 0;
+
+  if (!['public', 'licensed', 'remote'].includes(plan.access)) {
+    const unknownAccess = plan.access;
+    plan.access = null;
+    plan.state = 'invalid';
+    plan.required_action = 'block';
+    plan.issues.push(buildLoadPlanIssue(
+      'KDNA_ACCESS_MODE_UNKNOWN',
+      'blocking',
+      `Unknown access value "${unknownAccess}".`,
+    ));
+    return finalizeLoadPlan(plan);
+  }
+
+  if (plan.access === 'remote') {
+    plan.state = 'needs_runtime';
+    plan.required_action = 'connect_runtime';
+    plan.can_load_now = false;
+    plan.projection_policy = 'remote';
+    plan.issues.push(buildLoadPlanIssue(
+      'KDNA_AUTH_REMOTE_RUNTIME_REQUIRED',
+      'blocking',
+      'Remote assets require a runtime projection endpoint.',
+    ));
+    return finalizeLoadPlan(plan);
+  }
+
+  if (plan.access === 'licensed') {
+    const knownProfiles = new Set([
+      'password',
+      'local_receipt',
+      'account',
+      'org',
+      'purchase_receipt',
+      'device_bound',
+    ]);
+    if (plan.entitlement_profile && !knownProfiles.has(plan.entitlement_profile)) {
+      plan.state = 'invalid';
+      plan.required_action = 'block';
+      plan.can_load_now = false;
+      plan.projection_policy = 'none';
+      plan.issues.push(buildLoadPlanIssue(
+        'KDNA_ENTITLEMENT_PROFILE_UNKNOWN',
+        'blocking',
+        `Unknown entitlement profile "${plan.entitlement_profile}".`,
+      ));
+      return finalizeLoadPlan(plan);
+    }
+
+    if (plan.entitlement_profile === 'password') {
+      if (opts.password || opts.hasPassword === true) {
+        plan.state = 'ready';
+        plan.required_action = 'load';
+        plan.can_load_now = true;
+        plan.projection_policy = 'minimal';
+      } else {
+        plan.state = 'needs_password';
+        plan.required_action = 'enter_password';
+        plan.can_load_now = false;
+        plan.projection_policy = 'none';
+        plan.issues.push(buildLoadPlanIssue(
+          'KDNA_AUTH_PASSWORD_REQUIRED',
+          'blocking',
+          'A password is required before this asset can be loaded.',
+        ));
+      }
+      return finalizeLoadPlan(plan);
+    }
+
+    if (plan.entitlement_profile === 'account') {
+      plan.state = 'needs_account';
+      plan.required_action = 'sign_in_or_activate';
+      plan.can_load_now = false;
+      plan.projection_policy = 'none';
+      plan.issues.push(buildLoadPlanIssue(
+        'KDNA_AUTH_ACCOUNT_REQUIRED',
+        'blocking',
+        'Account authorization is required before this asset can be loaded.',
+      ));
+      return finalizeLoadPlan(plan);
+    }
+
+    if (plan.entitlement_profile === 'org') {
+      plan.state = 'needs_org_auth';
+      plan.required_action = 'sign_in_or_activate';
+      plan.can_load_now = false;
+      plan.projection_policy = 'none';
+      plan.issues.push(buildLoadPlanIssue(
+        'KDNA_AUTH_ORG_REQUIRED',
+        'blocking',
+        'Organization authorization is required before this asset can be loaded.',
+      ));
+      return finalizeLoadPlan(plan);
+    }
+
+    if (opts.entitlement && opts.entitlement.status === 'active') {
+      plan.state = 'ready';
+      plan.required_action = 'load';
+      plan.can_load_now = true;
+      plan.projection_policy = 'minimal';
+      return finalizeLoadPlan(plan);
+    }
+
+    if (opts.entitlement && opts.entitlement.status === 'expired') {
+      plan.state = 'expired';
+      plan.required_action = 'sync';
+      plan.can_load_now = false;
+      plan.projection_policy = 'none';
+      plan.issues.push(buildLoadPlanIssue(
+        'KDNA_AUTH_EXPIRED',
+        'blocking',
+        'The entitlement is expired.',
+      ));
+      return finalizeLoadPlan(plan);
+    }
+
+    if (opts.entitlement && opts.entitlement.status === 'revoked') {
+      plan.state = 'revoked';
+      plan.required_action = 'block';
+      plan.can_load_now = false;
+      plan.projection_policy = 'none';
+      plan.issues.push(buildLoadPlanIssue(
+        'KDNA_AUTH_REVOKED',
+        'blocking',
+        'The entitlement has been revoked.',
+      ));
+      return finalizeLoadPlan(plan);
+    }
+
+    if (opts.entitlement && opts.entitlement.status === 'offline_grace') {
+      plan.state = 'offline_grace';
+      plan.required_action = 'sync';
+      plan.can_load_now = true;
+      plan.projection_policy = 'minimal';
+      plan.issues.push(buildLoadPlanIssue(
+        'KDNA_AUTH_OFFLINE_GRACE_ACTIVE',
+        'warning',
+        'The entitlement can load during offline grace but must sync before grace expires.',
+      ));
+      return finalizeLoadPlan(plan);
+    }
+
+    plan.state = 'needs_license';
+    plan.required_action = plan.entitlement_profile === 'local_receipt' ? 'install_receipt' : 'sign_in_or_activate';
+    plan.can_load_now = false;
+    plan.projection_policy = 'none';
+    plan.issues.push(buildLoadPlanIssue(
+      'KDNA_AUTH_ENTITLEMENT_REQUIRED',
+      'blocking',
+      'A valid entitlement is required before this asset can be loaded.',
+    ));
+    return finalizeLoadPlan(plan);
+  }
+
+  if (hasEncryptedPayload) {
+    plan.state = 'invalid';
+    plan.required_action = 'block';
+    plan.can_load_now = false;
+    plan.projection_policy = 'none';
+    plan.issues.push(buildLoadPlanIssue(
+      'KDNA_CRYPTO_PROFILE_UNSUPPORTED',
+      'blocking',
+      'Encrypted entries require licensed access.',
+    ));
+    return finalizeLoadPlan(plan);
+  }
+
+  plan.state = 'ready';
+  plan.required_action = 'load';
+  plan.can_load_now = true;
+  plan.projection_policy = 'minimal';
+  return finalizeLoadPlan(plan);
+}
+
 function assertNoForbiddenTerms(obj) {
   const seen = new Set();
   function walk(o) {
@@ -781,6 +1105,7 @@ module.exports = {
   readV1Layout,
   inspect,
   validate,
+  planLoad,
   buildChecksumsV1,
   pack,
   unpack,

package/src/v1/index.mjs

@@ -9,6 +9,7 @@ export const detectContainerFormat = v1.detectContainerFormat;
 export const readV1Layout = v1.readV1Layout;
 export const inspect = v1.inspect;
 export const validate = v1.validate;
+export const planLoad = v1.planLoad;
 export const buildChecksumsV1 = v1.buildChecksumsV1;
 export const pack = v1.pack;
 export const unpack = v1.unpack;