@holoscript/holosystem 0.2.5 → 0.2.7

package/README.md

@@ -55,6 +55,48 @@ returns one highest-priority candidate, and carries authority, validation, lease
 and spend stop conditions. It selects work; it does not claim a board task,
 publish a package, spend funds, or bypass caller authority.
 
+## HoloScript Source Canon
+
+`source-canon` is the consumer-side language-sovereignty gate. Run it from the
+root of a Git repository:
+
+```bash
+npx holosystem source-canon \
+  --output runtime/visual-state/source-canon.hsplus \
+  --json
+```
+
+The gate reads the fixed Git-tracked file inventory and accepts only `.holo`,
+`.hs`, and `.hsplus` as canonical authored source. It then parses the actual
+tracked bytes with the exact optional peer `@holoscript/core@8.0.15`; when that
+parser is unavailable, the gate fails closed. This prevents JavaScript or another
+language from becoming canonical merely by being renamed. Other HoloSystem
+commands remain usable without the optional peer.
+
+A caller cannot widen the registry with an extension allowlist. A future format
+becomes canonical only when a HoloScript release owns its parser and adds it to
+the package registry.
+
+The command exits `0` only when at least one HoloScript source file exists and
+every tracked file uses a canonical format. It exits `2` with every foreign
+tracked path named otherwise. When `--output` is supplied, the durable
+founder-visible projection must itself be a portable repository-relative
+`.hsplus` path; JSON remains available only on standard output for transient
+agent pipelines.
+
+This gate audits Git-tracked canon. Dependency caches, runtime receipts, and
+untracked generated artifacts are not silently promoted to source truth. They
+remain non-canonical operational state and must stay untracked or move to an
+external runtime store as the consumer migration proceeds.
+
+```js
+import {
+  inspectGitTrackedSourceCanon,
+  inspectSourceCanon,
+  renderSourceCanonProjection,
+} from '@holoscript/holosystem';
+```
+
 ## Substrate Closure
 
 The substrate closure replaces an implicit operating-system dependency tower
@@ -749,6 +791,9 @@ npx holosystem inspect holosystem.config.json --json
 
 # Pipeline input is supported.
 npx holosystem create --stdout | npx holosystem inspect - --json
+
+# Prove that Git-tracked authoring is HoloScript-only.
+npx holosystem source-canon --output source-canon.hsplus --json
 ```
 
 Creation never installs packages, connects to storage, acquires credentials, or

package/bin/holosystem.mjs

@@ -10,6 +10,7 @@ import {
   importDebianPackageSnapshot,
   importNpmPackageLock,
   inspectNativeBuildSource,
+  inspectGitTrackedSourceCanon,
   inspectHoloSystemConfig,
   inspectVmExecutor,
   inspectVmLaunchAsset,
@@ -19,6 +20,7 @@ import {
   runWhpxAppContainerVmLaunch,
   runWhpxSandboxedVmLaunch,
   runWhpxVmLaunch,
+  renderSourceCanonProjection,
 } from '../src/index.mjs';
 
 const CLI_RECEIPT_SCHEMA = 'holoscript.holosystem.cli-receipt.v1';
@@ -34,6 +36,7 @@ Usage:
   holosystem substrate-import-debian --status <status> (--packages <Packages> | --sources <json>) --maintainer-scripts <json> --config <file> [--output <file>] [--force] [--json]
   holosystem native-build-source --source <directory> [--json]
   holosystem native-build --plan <file> --source <directory> --executor <file> --artifact-dir <directory> [--output <receipt>] [--force] [--json]
+  holosystem source-canon [--output <projection.hsplus>] [--force] [--json]
   holosystem vm-executor --runtime <directory> [--json]
   holosystem vm-asset --kind <kernel|initrd> --file <file> [--json]
   holosystem vm-launch --plan <file> --runtime <directory> --kernel <file> --initrd <file> [--output <receipt>] [--force] [--json]
@@ -206,6 +209,63 @@ function writeJsonOutput(path, value, { force = false } = {}) {
   writeFileSync(absolute, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
 }
 
+function writeSourceCanonProjection(path, value, { force = false } = {}) {
+  if (
+    typeof path !== 'string' ||
+    !path.endsWith('.hsplus') ||
+    /^[A-Za-z]:[\\/]/u.test(path) ||
+    /^(?:[\\/]{1,2}|~[\\/])/u.test(path) ||
+    path.replaceAll('\\', '/').split('/').some((segment) => segment === '..' || segment === '.')
+  ) {
+    throw new Error('--output must be a portable repository-relative .hsplus path.');
+  }
+  const absolute = resolve(process.cwd(), path);
+  if (existsSync(absolute) && !force)
+    throw new Error(`${path} already exists; use --force to replace it.`);
+  writeFileSync(absolute, value, 'utf8');
+}
+
+async function runSourceCanon(args) {
+  let parsed;
+  try {
+    parsed = parseArguments(args, {
+      output: 'value',
+      force: 'boolean',
+      json: 'boolean',
+    });
+  } catch (error) {
+    die(error.message, { json: args.includes('--json') });
+  }
+  const { options, positionals } = parsed;
+  if (positionals.length > 0) {
+    die('source-canon does not accept positional arguments.', { json: options.json });
+  }
+
+  let report;
+  try {
+    report = await inspectGitTrackedSourceCanon({ rootDirectory: process.cwd() });
+    if (options.output) {
+      writeSourceCanonProjection(options.output, renderSourceCanonProjection(report), {
+        force: options.force,
+      });
+    }
+  } catch (error) {
+    die(`Cannot inspect source canon: ${error.message}`, { json: options.json, code: 2 });
+  }
+
+  if (options.json) outputJson(report);
+  else {
+    process.stdout.write(
+      `Source canon: ${report.status} HoloScript=${report.summary.holoScriptFiles} foreign=${report.summary.foreignFiles}\n`
+    );
+    for (const issue of report.issues) {
+      process.stdout.write(`BLOCK ${issue.code} ${issue.path}: ${issue.message}\n`);
+    }
+    if (options.output) process.stdout.write(`Wrote ${options.output}\n`);
+  }
+  if (!report.verified) process.exitCode = 2;
+}
+
 function runInspect(args) {
   let parsed;
   try {
@@ -701,6 +761,8 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
   runNativeBuildSource(argv.slice(1));
 } else if (command === 'native-build') {
   runNativeBuildCommand(argv.slice(1));
+} else if (command === 'source-canon') {
+  await runSourceCanon(argv.slice(1));
 } else if (command === 'vm-executor') {
   runVmExecutor(argv.slice(1));
 } else if (command === 'vm-asset') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holoscript/holosystem",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Portable bootstrap, consumption catalog, lineage, and bounded-work contract for HoloSystem consumers.",
   "releaseLane": "v0-preview",
   "keywords": [
@@ -43,7 +43,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "node --check src/index.mjs && node --check src/catalog.mjs && node --check src/substrate.mjs && node --check src/substrate-import.mjs && node --check src/substrate-debian-release.mjs && node --check src/substrate-import-debian.mjs && node --check src/native-build.mjs && node --check src/vm-launch.mjs && node --check bin/holosystem.mjs",
+    "build": "node --check src/index.mjs && node --check src/catalog.mjs && node --check src/source-canon.mjs && node --check src/substrate.mjs && node --check src/substrate-import.mjs && node --check src/substrate-debian-release.mjs && node --check src/substrate-import-debian.mjs && node --check src/native-build.mjs && node --check src/vm-launch.mjs && node --check bin/holosystem.mjs",
     "test": "node --test test/*.test.mjs",
     "smoke": "node bin/holosystem.mjs --help",
     "check": "pnpm run build && pnpm run test && pnpm run smoke",
@@ -57,5 +57,13 @@
       "localBoundary": "Machine paths, credentials, private repositories, and operator state are caller inputs, never package defaults.",
       "supportBoundary": "Configuration, public discovery, lineage, and bounded selection are supported; installation, credential acquisition, board mutation, service mutation, spending, and publishing remain caller-authorized operations."
     }
+  },
+  "peerDependencies": {
+    "@holoscript/core": "8.0.15"
+  },
+  "peerDependenciesMeta": {
+    "@holoscript/core": {
+      "optional": true
+    }
   }
 }

package/src/index.mjs

@@ -58,6 +58,14 @@ export {
   runWhpxVmLaunch,
 } from './vm-launch.mjs';
 
+export {
+  HOLOSCRIPT_CANONICAL_SOURCE_EXTENSIONS,
+  HOLOSYSTEM_SOURCE_CANON_SCHEMA,
+  inspectGitTrackedSourceCanon,
+  inspectSourceCanon,
+  renderSourceCanonProjection,
+} from './source-canon.mjs';
+
 export {
   HOLOSYSTEM_CATALOG_SCHEMA,
   HOLOSYSTEM_CONSUMER_INPUT_SCHEMA,

package/src/source-canon.mjs

@@ -0,0 +1,307 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+
+export const HOLOSYSTEM_SOURCE_CANON_SCHEMA = 'holoscript.holosystem.source-canon.v1';
+export const HOLOSCRIPT_CANONICAL_SOURCE_EXTENSIONS = Object.freeze([
+  '.holo',
+  '.hs',
+  '.hsplus',
+]);
+
+const KNOWN_OPTIONS = new Set(['repository', 'trackedFiles', 'now']);
+const PORTABLE_ID = /^[a-z0-9][a-z0-9._-]{0,63}$/iu;
+
+function sha256(value) {
+  return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function requireKnownOptions(value) {
+  for (const key of Object.keys(value)) {
+    if (!KNOWN_OPTIONS.has(key)) throw new TypeError(`Unknown source-canon option ${key}.`);
+  }
+}
+
+function normalizeRepository(value = {}) {
+  if (!isRecord(value)) throw new TypeError('repository must be an object.');
+  const id = value.id ?? 'workspace';
+  const head = value.head ?? null;
+  if (!PORTABLE_ID.test(id)) throw new TypeError('repository.id must be a portable identifier.');
+  if (head !== null && (typeof head !== 'string' || !/^[a-f0-9]{7,64}$/iu.test(head))) {
+    throw new TypeError('repository.head must be a Git object id or null.');
+  }
+  return { id, head };
+}
+
+function normalizeTrackedPath(value) {
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    value.length > 512 ||
+    /[\0-\x1f\x7f]/u.test(value) ||
+    /^[A-Za-z]:[\\/]/u.test(value) ||
+    /^(?:[\\/]{1,2}|~[\\/])/u.test(value)
+  ) {
+    throw new TypeError(`${String(value)} is not a portable repository-relative path.`);
+  }
+  const normalized = value.replaceAll('\\', '/');
+  const segments = normalized.split('/');
+  if (
+    segments.some((segment) => segment === '' || segment === '.' || segment === '..') ||
+    normalized.startsWith('.//')
+  ) {
+    throw new TypeError(`${value} is not a portable repository-relative path.`);
+  }
+  return normalized;
+}
+
+function sourceExtension(path) {
+  return HOLOSCRIPT_CANONICAL_SOURCE_EXTENSIONS.find((extension) => path.endsWith(extension)) ?? null;
+}
+
+function foreignExtension(path) {
+  const name = path.slice(path.lastIndexOf('/') + 1);
+  const index = name.lastIndexOf('.');
+  return index <= 0 ? '<none>' : name.slice(index).toLowerCase();
+}
+
+function buildSourceCanonReport(options, { sources = {}, parser = null } = {}) {
+  const repository = normalizeRepository(options.repository);
+  if (options.trackedFiles !== undefined && !Array.isArray(options.trackedFiles)) {
+    throw new TypeError('trackedFiles must be an array.');
+  }
+
+  const files = (options.trackedFiles ?? []).map(normalizeTrackedPath).sort();
+  if (new Set(files).size !== files.length) throw new TypeError('trackedFiles must be unique.');
+
+  const generatedAt = new Date(options.now ?? Date.now());
+  if (Number.isNaN(generatedAt.getTime())) throw new TypeError('now must be a valid date.');
+
+  const holoScriptFiles = [];
+  const foreignFiles = [];
+  const byFormat = Object.fromEntries(
+    HOLOSCRIPT_CANONICAL_SOURCE_EXTENSIONS.map((extension) => [extension, 0])
+  );
+  const foreignByFormat = {};
+
+  for (const path of files) {
+    const extension = sourceExtension(path);
+    if (extension) {
+      holoScriptFiles.push(path);
+      byFormat[extension] += 1;
+      continue;
+    }
+    foreignFiles.push(path);
+    const foreign = foreignExtension(path);
+    foreignByFormat[foreign] = (foreignByFormat[foreign] ?? 0) + 1;
+  }
+
+  const issues = foreignFiles.map((path) => ({
+    code: 'foreign-source-format',
+    path,
+    message: 'Git-tracked canon must be authored in a parser-owned HoloScript source format.',
+  }));
+  if (holoScriptFiles.length === 0) {
+    issues.unshift({
+      code: 'holoscript-source-missing',
+      path: '$',
+      message: 'At least one Git-tracked .holo, .hs, or .hsplus source file is required.',
+    });
+  }
+
+  for (const path of Object.keys(sources)) {
+    const normalized = normalizeTrackedPath(path);
+    if (!holoScriptFiles.includes(normalized)) {
+      throw new TypeError(`Source ${path} is not a tracked canonical HoloScript path.`);
+    }
+    if (typeof sources[path] !== 'string') {
+      throw new TypeError(`Source ${path} must be a string.`);
+    }
+  }
+
+  const parseChecks = holoScriptFiles.map((path) => {
+    const source = sources[path];
+    if (typeof parser !== 'function' || typeof source !== 'string') {
+      issues.push({
+        code: 'holoscript-parse-evidence-missing',
+        path,
+        message:
+          'Canonical source requires repository-owned bytes and a real @holoscript/core parse result.',
+      });
+      return {
+        path,
+        status: 'not-run',
+        sourceDigest: typeof source === 'string' ? sha256(source) : null,
+        errors: [],
+      };
+    }
+    let parsed;
+    try {
+      parsed = parser(source);
+    } catch (error) {
+      parsed = {
+        success: false,
+        errors: [{ code: 'parser-threw', message: error?.message ?? String(error) }],
+      };
+    }
+    const errors = (Array.isArray(parsed?.errors) ? parsed.errors : []).slice(0, 8).map((error) => ({
+      code: error?.code ?? null,
+      message: error?.message ?? String(error),
+      line: Number.isInteger(error?.line) ? error.line : null,
+      column: Number.isInteger(error?.column) ? error.column : null,
+    }));
+    const passed = parsed?.success === true && errors.length === 0;
+    if (!passed) {
+      issues.push({
+        code: 'holoscript-source-invalid',
+        path,
+        message: 'Canonical source did not pass @holoscript/core.parse.',
+      });
+    }
+    return {
+      path,
+      status: passed ? 'passed' : 'failed',
+      sourceDigest: sha256(source),
+      errors,
+    };
+  });
+
+  const formatVerified = holoScriptFiles.length > 0 && foreignFiles.length === 0;
+  const parserVerified =
+    holoScriptFiles.length > 0 && parseChecks.every((item) => item.status === 'passed');
+  const verified = formatVerified && parserVerified && issues.length === 0;
+  const stableReceipt = {
+    schema: HOLOSYSTEM_SOURCE_CANON_SCHEMA,
+    scope: 'git-tracked-canon',
+    repository,
+    formatRegistry: [...HOLOSCRIPT_CANONICAL_SOURCE_EXTENSIONS],
+    trackedFiles: files,
+    holoScriptFiles,
+    foreignFiles,
+    parseChecks,
+    formatVerified,
+    parserVerified,
+  };
+
+  return {
+    schema: HOLOSYSTEM_SOURCE_CANON_SCHEMA,
+    generatedAt: generatedAt.toISOString(),
+    status: verified ? 'verified' : 'blocked',
+    verified,
+    formatVerified,
+    parserVerified,
+    scope: 'git-tracked-canon',
+    repository,
+    formatRegistry: {
+      owner: '@holoscript/holosystem',
+      extensions: [...HOLOSCRIPT_CANONICAL_SOURCE_EXTENSIONS],
+      callerExtensionsAccepted: false,
+      rule: 'New canonical extensions require a parser-owned HoloScript release; callers cannot widen the registry.',
+    },
+    summary: {
+      trackedFiles: files.length,
+      holoScriptFiles: holoScriptFiles.length,
+      foreignFiles: foreignFiles.length,
+      parsePassed: parseChecks.filter((item) => item.status === 'passed').length,
+      parseFailed: parseChecks.filter((item) => item.status === 'failed').length,
+      parseMissing: parseChecks.filter((item) => item.status === 'not-run').length,
+      byFormat,
+      foreignByFormat: Object.fromEntries(Object.entries(foreignByFormat).sort()),
+    },
+    holoScriptFiles,
+    foreignFiles,
+    parseChecks,
+    issues,
+    boundaries: {
+      untrackedRuntimeIsCanon: false,
+      dependencyCachesAreCanon: false,
+      generatedArtifactsAreCanonOnlyWhenTracked: true,
+      extensionOnlyClaimsAccepted: false,
+    },
+    receiptHash: sha256(JSON.stringify(stableReceipt)),
+  };
+}
+
+export function inspectSourceCanon(options = {}) {
+  if (!isRecord(options)) throw new TypeError('source-canon options must be an object.');
+  requireKnownOptions(options);
+  return buildSourceCanonReport(options);
+}
+
+function runGit(rootDirectory, args) {
+  const result = spawnSync('git', ['-C', rootDirectory, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.status !== 0) {
+    throw new Error(`Git ${args.join(' ')} failed: ${String(result.stderr || '').trim()}`);
+  }
+  return result.stdout;
+}
+
+export async function inspectGitTrackedSourceCanon({ rootDirectory = process.cwd(), now } = {}) {
+  const root = resolve(rootDirectory);
+  const repositoryRoot = resolve(runGit(root, ['rev-parse', '--show-toplevel']).trim());
+  if (repositoryRoot.toLowerCase() !== root.toLowerCase()) {
+    throw new Error('source-canon must run from the repository root.');
+  }
+  const idCandidate = basename(root).toLowerCase();
+  const repository = {
+    id: PORTABLE_ID.test(idCandidate) ? idCandidate : 'workspace',
+    head: runGit(root, ['rev-parse', 'HEAD']).trim(),
+  };
+  const trackedFiles = runGit(root, ['ls-files', '-z'])
+    .split('\0')
+    .filter(Boolean);
+  const sources = Object.fromEntries(
+    trackedFiles
+      .map(normalizeTrackedPath)
+      .filter((path) => sourceExtension(path))
+      .map((path) => [path, readFileSync(resolve(root, path), 'utf8')])
+  );
+  let parser = null;
+  try {
+    const core = await import('@holoscript/core');
+    if (typeof core.parse === 'function') parser = core.parse;
+  } catch {
+    // The report fails closed with parse-evidence-missing issues below.
+  }
+  return buildSourceCanonReport({ repository, trackedFiles, now }, { sources, parser });
+}
+
+export function renderSourceCanonProjection(report) {
+  if (!isRecord(report) || report.schema !== HOLOSYSTEM_SOURCE_CANON_SCHEMA) {
+    throw new TypeError(`Expected ${HOLOSYSTEM_SOURCE_CANON_SCHEMA}.`);
+  }
+  return `composition "HoloSystemSourceCanon" {
+  state {
+    status: "${report.status}"
+    verified: ${report.verified}
+    formatVerified: ${report.formatVerified}
+    parserVerified: ${report.parserVerified}
+    scope: "${report.scope}"
+    trackedFiles: ${report.summary.trackedFiles}
+    holoScriptFiles: ${report.summary.holoScriptFiles}
+    foreignFiles: ${report.summary.foreignFiles}
+    holoFiles: ${report.summary.byFormat['.holo']}
+    hsFiles: ${report.summary.byFormat['.hs']}
+    hsplusFiles: ${report.summary.byFormat['.hsplus']}
+    parsePassed: ${report.summary.parsePassed}
+    parseFailed: ${report.summary.parseFailed}
+    parseMissing: ${report.summary.parseMissing}
+    receiptHash: "${report.receiptHash}"
+  }
+
+  object "LanguageSovereignty" {
+    canonicalFormats: ".holo,.hs,.hsplus"
+    callerExtensionsAccepted: false
+    migrationRequired: ${!report.verified}
+  }
+}
+`;
+}