@aikdna/kdna-core 0.37.1-rc.browser.1 → 0.37.2

package/src/public-contract/public-contract.d.ts

@@ -0,0 +1,13 @@
+export type ContractViewKind = 'manifest' | 'payload' | 'judgment' | 'methodComponent' | 'catalogItem';
+export type ContractCoordinate = Readonly<Record<string, string>>;
+export interface ContractView {
+  readonly kinds: ReadonlyArray<ContractViewKind>;
+  contractCoordinate(): ContractCoordinate;
+  requiredKeys(kind: ContractViewKind): string[];
+  optionalKeys(kind: ContractViewKind): string[];
+}
+export declare function buildContractView(contract: unknown): ContractView;
+export declare const kinds: ReadonlyArray<ContractViewKind>;
+export declare function contractCoordinate(): ContractCoordinate;
+export declare function requiredKeys(kind: ContractViewKind): string[];
+export declare function optionalKeys(kind: ContractViewKind): string[];

package/src/public-contract/public-contract.js

@@ -0,0 +1,32 @@
+'use strict';
+// Read-only view over the public contract this installation ships. No contract
+// data lives in this file: every readout is derived from the generated contract
+// at call time, so a consumer checks against the contract it actually installed.
+const generated = require('./generated-contract.json');
+const KINDS = Object.freeze(['manifest', 'payload', 'judgment', 'methodComponent', 'catalogItem']);
+const TYPE_FOR_KIND = Object.freeze({
+  manifest: 'Manifest',
+  payload: 'Payload',
+  judgment: 'Judgment',
+  methodComponent: 'MethodComponent',
+  catalogItem: 'CatalogItem',
+});
+function keysFor(view, kind, which) {
+  const name = TYPE_FOR_KIND[kind];
+  if (!name) throw new Error('KDNA_CONTRACT_VIEW_UNKNOWN_KIND');
+  const type = view && view.types ? view.types[name] : undefined;
+  if (!type) throw new Error('KDNA_CONTRACT_VIEW_TYPE_MISSING');
+  const required = Array.isArray(type.required) ? [...type.required] : [];
+  if (which === 'required') return required;
+  return Object.keys(type.properties ?? {}).filter((key) => !required.includes(key));
+}
+function buildContractView(view) {
+  if (!view || typeof view !== 'object') throw new Error('KDNA_CONTRACT_VIEW_INPUT_INVALID');
+  return Object.freeze({
+    kinds: KINDS,
+    contractCoordinate: () => structuredClone(view.versionTuple ?? {}),
+    requiredKeys: (kind) => keysFor(view, kind, 'required'),
+    optionalKeys: (kind) => keysFor(view, kind, 'optional'),
+  });
+}
+module.exports = Object.freeze({ buildContractView, ...buildContractView(generated) });

package/src/public-contract/public-contract.mjs

@@ -0,0 +1,2 @@
+import view from './public-contract.js';
+export const {buildContractView,kinds,contractCoordinate,requiredKeys,optionalKeys}=view;

package/src/public-contract/retained/contract.json

@@ -2,8 +2,8 @@
   "candidate_only": true,
   "source": {
     "path": "specs/public-semantic-source.json",
-    "bytes": 1506884,
-    "sha256": "a05af27e97be03a8909375217ab353017b72a10532ad7d700b6ae278e30d1d5f"
+    "bytes": 1506715,
+    "sha256": "e1fa081ca757d8ceb2e73910024778e31debe83b16d8b4824a4c66466ec57928"
   },
   "historical_original_source": {
     "scope": "historical_original_contract_source_identity_not_current_generator_input",

package/src/public-contract/retained/generation-manifest.json

@@ -3,14 +3,14 @@
   "candidate_only": true,
   "source": {
     "path": "specs/public-semantic-source.json",
-    "bytes": 1506884,
-    "sha256": "a05af27e97be03a8909375217ab353017b72a10532ad7d700b6ae278e30d1d5f"
+    "bytes": 1506715,
+    "sha256": "e1fa081ca757d8ceb2e73910024778e31debe83b16d8b4824a4c66466ec57928"
   },
   "producer": {
     "recipe": {
       "path": "scripts/public-contract/native-output-recipe.json",
       "bytes": 164001,
-      "sha256": "076b8d75b26d3c675fb8f89768e7d3cdddc448f2f29b19adb28b768a0c4dfbfb"
+      "sha256": "f5258627e45d396f9b088e76bdabe699d9ab845678ce1fa6a855b3fdaec21f22"
     },
     "scripts": [
       {
@@ -20,8 +20,8 @@
       },
       {
         "path": "scripts/public-contract/native-renderer.mjs",
-        "bytes": 20169,
-        "sha256": "44806a5a6dc43b141791b62b3683acd3145ac14b67ee5e6077923c5c62ca0187"
+        "bytes": 21439,
+        "sha256": "750e968d0d88908f7c6b6b3d017039919049e22060203a7c721c3204522c211e"
       },
       {
         "path": "scripts/public-contract/generation-writer.mjs",
@@ -618,7 +618,7 @@
     {
       "path": "packages/kdna-core/src/public-contract/retained/contract.json",
       "bytes": 291233,
-      "sha256": "6675e6e72c76e89785da7d75c16fd29d66e2039047f14ef8b3a5e7517e0c4ac9"
+      "sha256": "c9ece7138801ceed528693d8277ea873e1eee874eb567ef35f0e38e72b238121"
     },
     {
       "path": "packages/kdna-core/src/public-contract/retained/api.d.ts",

package/src/public-contract/retained-browser06/contract.json

@@ -2,8 +2,8 @@
   "candidate_only": true,
   "source": {
     "path": "specs/public-semantic-source.json",
-    "bytes": 1506884,
-    "sha256": "a05af27e97be03a8909375217ab353017b72a10532ad7d700b6ae278e30d1d5f"
+    "bytes": 1506715,
+    "sha256": "e1fa081ca757d8ceb2e73910024778e31debe83b16d8b4824a4c66466ec57928"
   },
   "historical_original_source": {
     "scope": "historical_original_contract_source_identity_not_current_generator_input",

package/src/public-contract/sectionbytes/contract.json

@@ -2,8 +2,8 @@
   "candidate_only": true,
   "source": {
     "path": "specs/public-semantic-source.json",
-    "bytes": 1506884,
-    "sha256": "a05af27e97be03a8909375217ab353017b72a10532ad7d700b6ae278e30d1d5f"
+    "bytes": 1506715,
+    "sha256": "e1fa081ca757d8ceb2e73910024778e31debe83b16d8b4824a4c66466ec57928"
   },
   "historical_original_source": {
     "scope": "historical_original_contract_source_identity_not_current_generator_input",

package/src/public-contract/sectionbytes/generation-manifest.json

@@ -3,14 +3,14 @@
   "candidate_only": true,
   "source": {
     "path": "specs/public-semantic-source.json",
-    "bytes": 1506884,
-    "sha256": "a05af27e97be03a8909375217ab353017b72a10532ad7d700b6ae278e30d1d5f"
+    "bytes": 1506715,
+    "sha256": "e1fa081ca757d8ceb2e73910024778e31debe83b16d8b4824a4c66466ec57928"
   },
   "producer": {
     "recipe": {
       "path": "scripts/public-contract/native-output-recipe.json",
       "bytes": 164001,
-      "sha256": "076b8d75b26d3c675fb8f89768e7d3cdddc448f2f29b19adb28b768a0c4dfbfb"
+      "sha256": "f5258627e45d396f9b088e76bdabe699d9ab845678ce1fa6a855b3fdaec21f22"
     },
     "scripts": [
       {
@@ -20,8 +20,8 @@
       },
       {
         "path": "scripts/public-contract/native-renderer.mjs",
-        "bytes": 20169,
-        "sha256": "44806a5a6dc43b141791b62b3683acd3145ac14b67ee5e6077923c5c62ca0187"
+        "bytes": 21439,
+        "sha256": "750e968d0d88908f7c6b6b3d017039919049e22060203a7c721c3204522c211e"
       },
       {
         "path": "scripts/public-contract/generation-writer.mjs",
@@ -124,7 +124,7 @@
     {
       "path": "packages/kdna-core/src/public-contract/sectionbytes/contract.json",
       "bytes": 31759,
-      "sha256": "617c4d2e2fcbfebaa4df559fb39b61e729064ff6e4b458a24321a6284d44074a"
+      "sha256": "208423043515f4149dd8d0cbf270ae07dc137bf6f0b79a70bfe61f7996365f9f"
     },
     {
       "path": "packages/kdna-core/src/public-contract/sectionbytes/api.d.ts",

package/src/public-contract/sections/contract.json

@@ -2,8 +2,8 @@
   "candidate_only": true,
   "source": {
     "path": "specs/public-semantic-source.json",
-    "bytes": 1506884,
-    "sha256": "a05af27e97be03a8909375217ab353017b72a10532ad7d700b6ae278e30d1d5f"
+    "bytes": 1506715,
+    "sha256": "e1fa081ca757d8ceb2e73910024778e31debe83b16d8b4824a4c66466ec57928"
   },
   "historical_original_source": {
     "scope": "historical_original_contract_source_identity_not_current_generator_input",

package/src/public-contract/sections/generation-manifest.json

@@ -3,14 +3,14 @@
   "candidate_only": true,
   "source": {
     "path": "specs/public-semantic-source.json",
-    "bytes": 1506884,
-    "sha256": "a05af27e97be03a8909375217ab353017b72a10532ad7d700b6ae278e30d1d5f"
+    "bytes": 1506715,
+    "sha256": "e1fa081ca757d8ceb2e73910024778e31debe83b16d8b4824a4c66466ec57928"
   },
   "producer": {
     "recipe": {
       "path": "scripts/public-contract/native-output-recipe.json",
       "bytes": 164001,
-      "sha256": "076b8d75b26d3c675fb8f89768e7d3cdddc448f2f29b19adb28b768a0c4dfbfb"
+      "sha256": "f5258627e45d396f9b088e76bdabe699d9ab845678ce1fa6a855b3fdaec21f22"
     },
     "scripts": [
       {
@@ -20,8 +20,8 @@
       },
       {
         "path": "scripts/public-contract/native-renderer.mjs",
-        "bytes": 20169,
-        "sha256": "44806a5a6dc43b141791b62b3683acd3145ac14b67ee5e6077923c5c62ca0187"
+        "bytes": 21439,
+        "sha256": "750e968d0d88908f7c6b6b3d017039919049e22060203a7c721c3204522c211e"
       },
       {
         "path": "scripts/public-contract/generation-writer.mjs",
@@ -658,7 +658,7 @@
     {
       "path": "packages/kdna-core/src/public-contract/sections/contract.json",
       "bytes": 547981,
-      "sha256": "e9cf4069906c3bf30ecfda953de9d75983f3941a10695ce9546101057593c372"
+      "sha256": "f871a8be8a91105f4a1a7bd4930e712bf3b012ce8b6fd17def7cf4eaaef27379"
     },
     {
       "path": "packages/kdna-core/src/public-contract/protected-sections-node.d.ts",

package/src/public-contract/sections-bytes-node.js

@@ -33,6 +33,35 @@ function createNativeSectionByteReadAuthority(callback,signaturePolicy){
 function classify(code){
  return ['PROTECTION_BINDING_UNIMPLEMENTED','CHECKSUMS_PROFILE_UNSUPPORTED','SIGNATURE_PROFILE_UNSUPPORTED'].includes(code)?'unsupported':'rejected';
 }
+// F2: one bounded metadata classifier for the three public read entries. It reads
+// only two bounded windows - the EOCD tail and the central directory - never the
+// whole container, and it never mutates a shared module. Empty input (no ZIP
+// structure) is reported as READ_INPUT_INVALID; a container that is recognisable
+// but damaged keeps READ_CORE_INVALID (the published Python contract pins that
+// for damaged member streams); a readable container of another family (a
+// payload-family member set) is reported as READ_UNSUPPORTED_VERSION.
+const INPUT_MARKERS={eocd:Uint8Array.from([80,75,5,6]),payload:Uint8Array.from([112,97,121,108,111,97,100,46,107,100,110,97,98]),frames:Uint8Array.from([115,101,99,116,105,111,110,115,47,112,97,99,107,45])};
+const INPUT_TAIL=65557,DIR_SCAN_CAP=1048576;
+function findBytes(bytes,needle,from=0,to=bytes.length){const last=Math.min(to,bytes.length)-needle.length;outer:for(let i=from;i<=last;i++){for(let j=0;j<needle.length;j++)if(bytes[i+j]!==needle[j])continue outer;return i;}return -1;}
+function containerMeta(bytes){
+ const view=bytes&&bytes.length>=4?bytes:null;
+ const zipMagic=view&&view[0]===0x50&&view[1]===0x4b&&(view[2]===0x03||view[2]===0x05||view[2]===0x07);
+ const tailStart=Math.max(0,bytes.length-INPUT_TAIL),eocd=bytes.length>=22?findBytes(bytes,INPUT_MARKERS.eocd,tailStart):-1;
+ if(!zipMagic&&eocd===-1)return {kind:'not_container'};
+ if(eocd===-1)return {kind:'damaged'};
+ const cdStart=(bytes[eocd+16]|(bytes[eocd+17]<<8)|(bytes[eocd+18]<<16)|(bytes[eocd+19]<<24))>>>0;
+ const cdSize=(bytes[eocd+12]|(bytes[eocd+13]<<8)|(bytes[eocd+14]<<16)|(bytes[eocd+15]<<24))>>>0;
+ if(cdStart+cdSize>bytes.length||cdSize>DIR_SCAN_CAP)return {kind:'damaged'};
+ const hasPayload=findBytes(bytes,INPUT_MARKERS.payload,cdStart,cdStart+cdSize)!==-1;
+ const hasFrames=findBytes(bytes,INPUT_MARKERS.frames,cdStart,cdStart+cdSize)!==-1;
+ return hasPayload&&!hasFrames?{kind:'other_family'}:{kind:'damaged'};
+}
+function inputFailureClass(bytes){
+ const meta=containerMeta(bytes);
+ if(meta.kind==='not_container')return {reason:'READ_INPUT_INVALID',stage:'input',diagnostic:null};
+ if(meta.kind==='other_family')return {reason:'READ_UNSUPPORTED_VERSION',stage:'metadata',diagnostic:{field:'/payload.kdnab',subject:null}};
+ return null;
+}
 async function admitSectionBytesNode(input,admitted,authority){
  let capture,owned,length=null,stage='input';
  const io=[];
@@ -84,6 +113,8 @@ async function admitSectionBytesNode(input,admitted,authority){
  }catch(error){
   const nativeFailure=C.isFailure(error),semanticFailure=knownSemanticReasons.has(error?.reason);
   const code=nativeFailure?error.code:semanticFailure?error.reason:'READ_CORE_CAPABILITY_UNAVAILABLE';
+ const classified=stage==='input'&&code==='READ_CORE_INVALID'?inputFailureClass(owned):null;
+ if(classified){stage=classified.stage;return failure(classify(classified.reason),classified.reason,classified.diagnostic);}
   return failure(classify(code),code,nativeFailure||semanticFailure?error?.diagnostic:null);
  }finally{
   if(capture)await capture.close();

package/src/public-contract/sections-node.js

@@ -1,6 +1,8 @@
 'use strict';
 const knownSemanticReasons=new Set(['READ_INPUT_INVALID','READ_CORE_INVALID','READ_CORE_CAPABILITY_UNAVAILABLE','READ_UNSUPPORTED_CRITICAL','READ_INTERPRETATION_INCOMPLETE','READ_STATIC_POLICY_INVALID',...require('./generated-contract.json').types.CoreComponentFailure.properties.code.enum]);
 const {inflateRawSync}=require('node:zlib');
+const fsp=require('node:fs/promises');
+const fsFlags=require('node:fs').constants;
 const C=require('./section-common.js'),{openSectionCapture}=require('./section-capture-node.js'),{parseSectionContainer}=require('./section-container.js'),{restoreWholeFrames}=require('./section-frame-graph.js'),{reconstructPayload}=require('./section-reconstruct.js'),{observeWhole}=require('./section-digests.js');
 const {validateDecodedPayload,assertContentBindings}=require('./semantic-admission.js'),{buildIR}=require('./canonical-ir.js'),{digestCanonical,evidence}=require('./digests.js');
 const {requests,snapshots,byteOrigins}=require('./section-native-state.js'),authorities=new WeakMap();
@@ -39,7 +41,40 @@ async function executeSectionNode(input,admitted,authority,operation='read',opti
   const data={digests,snapshot_id:'section-snapshot:'+globalThis.crypto.randomUUID(),tuple:structuredClone(tuple),asset:structuredClone(payload.asset),ir:derived,runtime_entry_names:observations.E.member_names,verification};C.validate('WholeSectionSnapshotData06',data);
   const view=C.strict.freeze(data),snapshot=Object.freeze({});snapshots.set(snapshot,view);expansion.retain(snapshot,view,capture);
   return Object.freeze({status:'accepted',snapshot,io:C.strict.freeze(structuredClone(capture.io)),input_byte_length:bytes.length});
- }catch(e){if(e?.result_stage)stage=e.result_stage;const nativeFailure=C.isFailure(e),semanticFailure=knownSemanticReasons.has(e?.reason);const code=nativeFailure?e.code:semanticFailure?e.reason:e?.code==='CONTAINER_COMMENT_CAPTURE_UNIMPLEMENTED'?e.code:'READ_CORE_CAPABILITY_UNAVAILABLE';return failure(classify(code),code,nativeFailure||semanticFailure?e?.diagnostic:null,structuredClone(capture?.io??e?.capture_io??[]));}finally{if(ownedSeed)ownedSeed.fill(0);if(capture)await capture.close();}
+ }catch(e){if(e?.result_stage)stage=e.result_stage;const nativeFailure=C.isFailure(e),semanticFailure=knownSemanticReasons.has(e?.reason);const code=nativeFailure?e.code:semanticFailure?e.reason:e?.code==='CONTAINER_COMMENT_CAPTURE_UNIMPLEMENTED'?e.code:'READ_CORE_CAPABILITY_UNAVAILABLE';const classified=stage==='input'&&code==='READ_CORE_INVALID'?await pathInputClass(input):null;if(classified){stage=classified.stage;return failure(classify(classified.reason),classified.reason,classified.diagnostic,structuredClone(capture?.io??e?.capture_io??[]));}return failure(classify(code),code,nativeFailure||semanticFailure?e?.diagnostic:null,structuredClone(capture?.io??e?.capture_io??[]));}finally{if(ownedSeed)ownedSeed.fill(0);if(capture)await capture.close();}
+}
+// F2: the same bounded metadata classifier as the two byte entries, expressed for
+// a file path. It reads only the head, the EOCD tail window and the central
+// directory - never content members - and it changes no shared module. Rules:
+// no container structure at all -> READ_INPUT_INVALID; recognisable but damaged
+// (including whole-file truncation) -> READ_CORE_INVALID unchanged; the central
+// directory declaring a payload-family member set -> READ_UNSUPPORTED_VERSION.
+const INPUT_MARKERS={eocd:Uint8Array.from([80,75,5,6]),payload:Uint8Array.from([112,97,121,108,111,97,100,46,107,100,110,97,98]),frames:Uint8Array.from([115,101,99,116,105,111,110,115,47,112,97,99,107,45])};
+const INPUT_TAIL=65557,DIR_SCAN_CAP=1048576;
+function findBytes(buf,needle,from=0,to=buf.length){const last=Math.min(to,buf.length)-needle.length;outer:for(let i=from;i<=last;i++){for(let j=0;j<needle.length;j++)if(buf[i+j]!==needle[j])continue outer;return i;}return -1;}
+function findLastBytes(buf,needle){for(let i=buf.length-needle.length;i>=0;i--){let ok=true;for(let j=0;j<needle.length;j++)if(buf[i+j]!==needle[j]){ok=false;break;}if(ok)return i;}return -1;}
+async function pathInputClass(file){
+ try{
+  // Classification follows a rejected capture, so the path is still untrusted.
+  // A blocking reopen of a FIFO would wait indefinitely for a writer.
+  const fh=await fsp.open(file,fsFlags.O_RDONLY|fsFlags.O_NONBLOCK);
+  try{
+   const st=await fh.stat();
+   if(!st.isFile()||!Number.isSafeInteger(st.size)||st.size<0)return {reason:'READ_INPUT_INVALID',stage:'input',diagnostic:null};
+   const head=Buffer.alloc(4),{bytesRead}=await fh.read(head,0,Math.min(4,st.size),0);
+   const zip=bytesRead===4&&head[0]===0x50&&head[1]===0x4b&&(head[2]===0x03||head[2]===0x05||head[2]===0x07);
+   // A recognisable ZIP shorter than an EOCD is damaged, as in both byte entries.
+   if(st.size<22)return zip?null:{reason:'READ_INPUT_INVALID',stage:'input',diagnostic:null};
+   const tailLen=Math.min(st.size,INPUT_TAIL),tail=Buffer.alloc(tailLen);await fh.read(tail,0,tailLen,st.size-tailLen);
+   const eocd=findLastBytes(tail,INPUT_MARKERS.eocd);
+   if(eocd===-1)return zip?null:{reason:'READ_INPUT_INVALID',stage:'input',diagnostic:null};
+   const cdStart=tail.readUInt32LE(eocd+16),cdSize=tail.readUInt32LE(eocd+12);
+   if(cdStart+cdSize>st.size||cdSize===0||cdSize>DIR_SCAN_CAP)return null;
+   const dir=Buffer.alloc(cdSize);await fh.read(dir,0,cdSize,cdStart);
+   const hasPayload=findBytes(dir,INPUT_MARKERS.payload)!==-1,hasFrames=findBytes(dir,INPUT_MARKERS.frames)!==-1;
+   return hasPayload&&!hasFrames?{reason:'READ_UNSUPPORTED_VERSION',stage:'metadata',diagnostic:{field:'/payload.kdnab',subject:null}}:null;
+  }finally{await fh.close();}
+ }catch{return null;}
 }
 async function admitSectionNode(input,admitted,authority){return executeSectionNode(input,admitted,authority);}
 async function createSectionChecksumsNode(input,admitted,authority){return executeSectionNode(input,admitted,authority,'produce_checksums');}