@tiinex/core 0.22.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiinex/core",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Shared host-neutral Tiinex implementation core for artifacts, schemas, validation, lineage, grounding, Handoffs, provenance and deterministic workflows.",
   "type": "module",
   "sideEffects": true,
@@ -140,7 +140,8 @@
     "./tooling/portable/comparison/sourceFrontierComparison.js": "./src/tooling/portable/comparison/sourceFrontierComparison.js",
     "./tooling/portable/adapters/node/sourceFrontierComparison.js": "./src/tooling/portable/adapters/node/sourceFrontierComparison.js",
     "./tooling/portable/handoff/recoveryAcceptanceAudit.js": "./src/tooling/portable/handoff/recoveryAcceptanceAudit.js",
-    "./tooling/portable/grounding/grounding.delegationReadiness.js": "./src/tooling/portable/grounding/grounding.delegationReadiness.js"
+    "./tooling/portable/grounding/grounding.delegationReadiness.js": "./src/tooling/portable/grounding/grounding.delegationReadiness.js",
+    "./tooling/portable/workspace/workspace.initialize.js": "./src/tooling/portable/workspace/workspace.initialize.js"
   },
   "files": [
     "src",
@@ -172,12 +173,12 @@
     "type": "git",
     "url": "git+https://github.com/Tiinex/core.git"
   },
-  "gitHead": "8a8e2e2e1b04eae1e5038116c69a449ad8f01349",
+  "gitHead": "0115723fd777d088edda56f7d9d1bef898b359ff",
   "tiinexRelease": {
     "policy": "tiinex.master-npm-release.v1",
-    "sourceCommit": "8a8e2e2e1b04eae1e5038116c69a449ad8f01349",
-    "sourceTree": "4596c4e041fb7c7067854f60c7daf68fd631e1f2",
+    "sourceCommit": "0115723fd777d088edda56f7d9d1bef898b359ff",
+    "sourceTree": "066320bc97b3d3d16caac487ae56a34c039bb1e2",
     "repository": "Tiinex/core",
-    "previousVersion": "0.21.0"
+    "previousVersion": "0.22.0"
   }
 }

package/src/tooling/portable/adapters/cli/cli.run.js

@@ -9,6 +9,7 @@ import { commandInput } from './cli.command-input.js';
 import { continueGroundWithHostResult } from './cli.ground-recovery.js';
 import { groundContinuationOperationInput, materializeGroundWorkspaceCliOutput } from './cli.ground-materialize.js';
 import { runCommonAuthorCli } from './cli.common-author.js';
+import { runCommonWorkspaceInitCli } from './cli.workspace-init.js';
 import { projectCommonCliDefaultOutput } from './cli.common-output.js';
 
 export async function runPortableCli(argv = process.argv.slice(2), io = console, runtime = {}) {
@@ -27,6 +28,11 @@ export async function runPortableCli(argv = process.argv.slice(2), io = console,
       writeJson(io, result, parsed.flags.compact !== true);
       return result?.findingSummary?.counts?.error ? 2 : 0;
     }
+    if (parsed.command === 'init-workspace') {
+      const result = await runCommonWorkspaceInitCli(parsed, runtime);
+      writeJson(io, result, parsed.flags.compact !== true);
+      return result?.findingSummary?.counts?.error ? 2 : 0;
+    }
     const timingEnabled = Boolean(parsed.flags['phase-timing']);
     const totalStartedAt = timingEnabled ? monotonicNowMs() : 0;
 

package/src/tooling/portable/adapters/cli/cli.workspace-init.js

@@ -0,0 +1,31 @@
+import path from 'node:path';
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { preparePortableWorkspaceInitialization } from '../../workspace/workspace.initialize.js';
+
+export async function runCommonWorkspaceInitCli(parsed = {}) {
+  const root = path.resolve(String(parsed.positionals?.[0] || '').trim() || '.');
+  const flags = parsed.flags || {};
+  const schemaMaterialPath = String(flags['schema-material'] || '').trim();
+  const schemaMarkdown = schemaMaterialPath ? await readFile(path.resolve(schemaMaterialPath), 'utf8') : '';
+  const result = preparePortableWorkspaceInitialization({
+    title: String(flags.title || flags['workspace-title'] || '').trim(),
+    workspaceId: String(flags['workspace-id'] || '').trim(),
+    repository: String(flags.repository || '').trim(),
+    ref: String(flags.ref || '').trim(),
+    sourceKind: String(flags['source-kind'] || '').trim(),
+    rootPath: String(flags['root-path'] || '.').trim(),
+    authors: String(flags.authors || '').trim(),
+    schemaTarget: String(flags['schema-target'] || '').trim(),
+    schemaMarkdown,
+    sameRepositorySchema: flags['same-repository-schema'] === true
+  });
+  if (result.status !== 'ready') return Object.freeze({ ...result, root });
+  const target = path.resolve(root, ...String(result.path).split('/'));
+  const rel = path.relative(root, target);
+  if (!rel || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) throw new Error('portable.workspace-init.target-outside-root');
+  try { await access(target); throw new Error(`portable.workspace-init.target-exists:${result.path}`); }
+  catch (error) { if (String(error?.message || '').startsWith('portable.workspace-init.target-exists:')) throw error; }
+  await mkdir(path.dirname(target), { recursive: true });
+  await writeFile(target, result.markdown, { encoding: 'utf8', flag: 'wx' });
+  return Object.freeze({ ...result, root, writeReceipt: Object.freeze({ path: target, workspaceRelativePath: result.path, bytes: Buffer.byteLength(result.markdown, 'utf8') }) });
+}

package/src/tooling/portable/draft/draft.create.js

@@ -24,13 +24,14 @@ export function createPortableLocalDraft(input = {}, options = {}) {
   const hasDeclaredParent = portableParentRecordHasAnyValue(parentRecord);
   const hasCompleteParent = portableParentRecordIsComplete(parentRecord);
   const exactParentQualification = qualifyPortableExactParent(parentRecord, transitionType);
-  const localContinuityParentCompatible = exactParentQualification.state === 'qualified-local-continuity';
-  const parentRenderable = exactParentQualification.state === 'qualified' || localContinuityParentCompatible;
-  const qualifiedParentRecord = parentRenderable ? exactParentQualification.snapshot : null;
-  const genericParentRecord = transitionType === 'create-artifact' ? parentRecord : qualifiedParentRecord;
-  const exactRendererParentCompatible = exactParentQualification.state === 'qualified';
+  const rootCreation = transitionType === 'create-artifact';
+  const localContinuityParentCompatible = !rootCreation && exactParentQualification.state === 'qualified-local-continuity';
+  const parentRenderable = rootCreation ? !hasDeclaredParent : exactParentQualification.state === 'qualified' || localContinuityParentCompatible;
+  const qualifiedParentRecord = rootCreation ? null : parentRenderable ? exactParentQualification.snapshot : null;
+  const genericParentRecord = rootCreation ? parentRecord : qualifiedParentRecord;
+  const exactRendererParentCompatible = rootCreation ? !hasDeclaredParent : exactParentQualification.state === 'qualified';
   const exactRendererEligible = exactContract.status === 'ready' && exactRendererParentCompatible;
-  const localContinuityRendererEligible = exactContract.status === 'ready' && localContinuityParentCompatible;
+  const localContinuityRendererEligible = !rootCreation && exactContract.status === 'ready' && localContinuityParentCompatible;
   if (!schemaId) findings.push(portableFinding('error', 'portable.draft-create.schema.required', 'Local draft creation requires a target schema id.'));
   if (hasDeclaredParent && !hasCompleteParent) findings.push(portableFinding('error', 'portable.draft-create.parent.incomplete', 'A declared Parent must provide explicit Parent Schema authority, Trace (or an explicit parent id), and a recoverable Origin path. A kind label is not Parent Schema authority.', {
     hasParentSchema: Boolean(parentRecord.schemaId || parentRecord.currentSchemaId),

package/src/tooling/portable/editor/editor.assistance.js

@@ -47,7 +47,7 @@ function projectDocument(record = {}, records = [], lineageInspection = null) {
     sourceSha256: sha256Hex(new TextEncoder().encode(markdown)),
     replacementMarkdown: workspacePackagingRepair.markdown,
     diagnosticCodes: workspacePackagingRepair.diagnosticCodes,
-    boundary: 'Repairs only a tiinex.workspace.v1 artifact whose replacement independently qualifies through the same exact registered Workspace contract and c14n-v2 self-integrity requirements used by Handoff package manufacture. A linked Current Schema target is normalized to the registered schema identifier only when the linked target itself is not qualified; no repository, Workspace, Handoff, Role, or authority meaning is invented.'
+    boundary: 'Repairs only a tiinex.workspace.v1 artifact whose replacement independently qualifies through the same exact registered Workspace contract and c14n-v2 self-integrity requirements used by Handoff package manufacture. Existing resolver-capable Current Schema references are preserved; permalink refresh is a separate resolution operation and must not be inferred from integrity repair.'
   }));
   const integrityRepair = deterministicIntegrityHygieneRepair(markdown, audit.findings || []);
   const repairQualification = integrityRepair.state === 'ready'
@@ -99,13 +99,11 @@ function deterministicWorkspacePackagingRepair(record = {}, audit = {}, markdown
   const bare = currentRaw === 'tiinex.workspace.v1';
   if (!linked && !bare) return freeze({ state: 'unavailable' });
 
+  // Current Schema is portable source identity, not a registry token. Preserve any
+  // already-resolvable external permalink; hosts/Core resolution may later offer a
+  // separate permalink refresh only when the resolved schema bytes actually changed.
   let candidate = source;
-  let schemaReferenceChanged = false;
-  const schemaAuthorityUnqualified = (audit.findings || []).some((item) => String(item.code || '') === 'audit.schema-authority.unqualified');
-  if (linked && schemaAuthorityUnqualified) {
-    candidate = candidate.replace(currentMatches[0][0], `${currentMatches[0][1]}tiinex.workspace.v1`);
-    schemaReferenceChanged = true;
-  }
+  const schemaReferenceChanged = false;
 
   const sealed = sealC14nV2Self(candidate);
   if (sealed.state !== 'sealed' && sealed.state !== 'unchanged') return freeze({ state: 'unavailable' });

package/src/tooling/portable/workspace/workspace.initialize.js

@@ -0,0 +1,80 @@
+import path from 'node:path';
+import { parseArtifactMarkdown } from '../../../artifacts/artifact.parse.js';
+import { sealC14nV2Self, canonicalC14nV2SelfState } from '../../../integrity/integrity.c14nV2.js';
+import { integrityMethodReferenceAuthorityForCreation, C14N_V2_METHOD_ID } from '../../../integrity/integrity.methodReference.js';
+import { schemaReferenceAuthorityForRegisteredSchema } from '../../../schemas/creation.schemaReferences.js';
+import { compilePortableSchemaContract } from '../schema/contract.compile.js';
+import { workspaceValidate } from '../../../schemas/workspace/tiinex.workspace.v1.validate.js';
+
+export const PORTABLE_WORKSPACE_INITIALIZATION_SCHEMA_ID = 'tiinex.portable.workspace-initialization.v1';
+export const WORKSPACE_SCHEMA_RESOLUTION_REQUEST = Object.freeze({
+  schemaId: 'tiinex.workspace.v1',
+  repository: 'Tiinex/docs',
+  path: '.topics/.schemas/tiinex.workspace.v1.schema.md',
+  resolution: 'latest-commit-permalink-plus-exact-schema-bytes',
+  boundary: 'The host resolves bytes; Core validates schema identity and owns rendered Workspace semantics. A commit change alone is not schema-change evidence.'
+});
+
+export function preparePortableWorkspaceInitialization(input = {}) {
+  const findings = [];
+  const title = clean(input.title || input.workspaceId || repositoryLeaf(input.repository) || 'Workspace');
+  const workspaceId = slug(input.workspaceId || repositoryLeaf(input.repository) || title);
+  const schemaTarget = String(input.schemaTarget || input.schemaResolution?.target || '').trim();
+  const schemaMarkdown = String(input.schemaMarkdown || input.schemaResolution?.markdown || '');
+  if (!schemaTarget || !schemaMarkdown) return Object.freeze({
+    schema: PORTABLE_WORKSPACE_INITIALIZATION_SCHEMA_ID,
+    status: 'needs-resolution',
+    resolutionRequest: WORKSPACE_SCHEMA_RESOLUTION_REQUEST,
+    findingSummary: summary([]),
+    findings: Object.freeze([])
+  });
+  if (!isResolvableSchemaTarget(schemaTarget, input.sameRepositorySchema === true)) findings.push(finding('error', 'workspace.initialize.schema-target.unresolvable', 'Workspace Current Schema must remain resolvable: use a same-repository relative target or an absolute permalink.', { schemaTarget }));
+  let compiled = null;
+  try { compiled = compilePortableSchemaContract(schemaMarkdown); }
+  catch (error) { findings.push(finding('error', 'workspace.initialize.schema-material.invalid', 'Resolved Workspace schema material could not be compiled.', { detail: String(error?.message || error || '') })); }
+  if (compiled && String(compiled.schemaId || '') !== 'tiinex.workspace.v1') findings.push(finding('error', 'workspace.initialize.schema-id.mismatch', 'Resolved schema material is not tiinex.workspace.v1.', { observed: compiled.schemaId || '' }));
+
+  const repository = clean(input.repository || '');
+  const ref = clean(input.ref || '');
+  const sourceKind = clean(input.sourceKind || (repository ? 'github-tree' : 'local-session'));
+  const rootPath = clean(input.rootPath || '.');
+  const createdAt = timestamp(input.createdAt || new Date());
+  const authors = clean(input.authors || 'local-user');
+  const envelopeTarget = String(schemaReferenceAuthorityForRegisteredSchema('tiinex.root.v1')?.preferredTarget || '').trim();
+  const integrityTarget = String(integrityMethodReferenceAuthorityForCreation(C14N_V2_METHOD_ID)?.preferredTarget || '').trim();
+  if (!envelopeTarget) findings.push(finding('error', 'workspace.initialize.root-schema.unresolved', 'Core could not resolve canonical tiinex.root.v1 authority.'));
+  if (!integrityTarget) findings.push(finding('error', 'workspace.initialize.integrity-method.unresolved', 'Core could not resolve canonical c14n-v2 validator authority.'));
+  if (findings.some((item) => item.severity === 'error')) return blocked(findings);
+
+  const entrypoint = repository ? `\n## Workspace Entrypoints\n\n### Repository source\n\n- Source Kind: ${sourceKind}\n- Repository: ${repository}${ref ? `\n- Ref: ${ref}` : ''}\n- Root Path: ${rootPath}\n- Repo Files Discovery: on\n` : '';
+  const unsigned = `# Continuity Context\n\n- Envelope Schema: [tiinex.root.v1](${envelopeTarget})\n- Current\n  - Current Schema: [tiinex.workspace.v1](${schemaTarget})\n  - Created At: ${createdAt}\n  - Authors: ${authors}\n  - Why: Establish an explicit portable Workspace entrypoint for this repository.\n  - Summary: ${title} Workspace.\n  - Status: active/local\n\n---\n\n# ${title}${entrypoint}\n# Continuity Integrity\n\n- [sha256-base64url-c14n-v2](${integrityTarget})\n  - Towards: self\n  - Value: pending\n`;
+  const sealed = sealC14nV2Self(unsigned);
+  if (sealed.state !== 'sealed') return blocked([finding('error', 'workspace.initialize.integrity-seal.failed', 'Core could not seal Workspace c14n-v2 self integrity.', { reason: sealed.reason || sealed.state })]);
+  const parsed = parseArtifactMarkdown(sealed.markdown);
+  for (const item of workspaceValidate(parsed) || []) if (item?.severity === 'error') findings.push(finding('error', item.code || 'workspace.initialize.workspace-validation', item.message || 'Workspace validation failed.'));
+  const integrity = canonicalC14nV2SelfState(sealed.markdown);
+  if (integrity.state !== 'verified') findings.push(finding('error', 'workspace.initialize.integrity-verification.failed', 'Generated Workspace self integrity did not verify.', { reason: integrity.reason || integrity.state }));
+  if (String(parsed?.envelope?.current?.schema?.id || '') !== 'tiinex.workspace.v1') findings.push(finding('error', 'workspace.initialize.current-schema.mismatch', 'Generated Workspace Current Schema identity is not tiinex.workspace.v1.'));
+  if (findings.some((item) => item.severity === 'error')) return blocked(findings);
+  return Object.freeze({
+    schema: PORTABLE_WORKSPACE_INITIALIZATION_SCHEMA_ID,
+    status: 'ready',
+    workspaceId,
+    path: `.topics/.workspaces/${workspaceId}.workspace.md`,
+    markdown: sealed.markdown,
+    schemaReference: Object.freeze({ schemaId: 'tiinex.workspace.v1', target: schemaTarget }),
+    repository: Object.freeze({ repository, ref, sourceKind, rootPath }),
+    findingSummary: summary(findings),
+    findings: Object.freeze(findings),
+    boundary: 'Core owns Workspace artifact semantics, schema-reference preservation, and integrity. Hosts only resolve requested external schema bytes and perform the explicit filesystem write.'
+  });
+}
+
+function blocked(findings) { return Object.freeze({ schema: PORTABLE_WORKSPACE_INITIALIZATION_SCHEMA_ID, status: 'blocked', resolutionRequest: WORKSPACE_SCHEMA_RESOLUTION_REQUEST, findingSummary: summary(findings), findings: Object.freeze(findings) }); }
+function finding(severity, code, message, evidence = {}) { return Object.freeze({ severity, code, message, source: PORTABLE_WORKSPACE_INITIALIZATION_SCHEMA_ID, evidence: Object.freeze({ ...evidence }) }); }
+function summary(findings) { const counts={error:0,warning:0,info:0,total:findings.length}; for(const item of findings) if(counts[item.severity]!==undefined) counts[item.severity]+=1; return Object.freeze({status:counts.error?'blocked':counts.warning?'degraded':'clean',counts:Object.freeze(counts)}); }
+function clean(value) { return String(value ?? '').trim().replace(/[\r\n]+/g, ' '); }
+function slug(value) { const out=clean(value).toLowerCase().replace(/[^a-z0-9]+/g,'-').replace(/^-+|-+$/g,''); return out || 'workspace'; }
+function repositoryLeaf(value) { const text=clean(value).replace(/\.git$/i,'').replace(/[\\/]+$/,''); return text.split(/[\\/]/).filter(Boolean).at(-1) || ''; }
+function timestamp(value) { const date=value instanceof Date?value:new Date(value); if(Number.isNaN(date.getTime())) return clean(value); return date.toISOString().replace('T',' ').replace(/\.\d{3}Z$/,''); }
+function isResolvableSchemaTarget(value, sameRepository) { if(sameRepository && !/^[a-z][a-z0-9+.-]*:/i.test(value) && !value.startsWith('/')) return true; try { const url=new URL(value); return ['https:','http:'].includes(url.protocol); } catch { return false; } }