@tiinex/core 0.1.1

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

@@ -0,0 +1,173 @@
+import { parseArtifactMarkdown } from '../../../artifacts/artifact.parse.js';
+import { createArtifactDraftMarkdown, renderArtifactCreationCandidateMarkdown, validateArtifactCreationResult } from '../../../schemas/creation.contracts.js';
+
+const ROOT_TIMESTAMP_SHAPE = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
+
+export function normalizePortableParentRecord(parent = {}) {
+  return Object.freeze({
+    id: String(parent.id || ''),
+    path: String(parent.path || ''),
+    kind: String(parent.kind || ''),
+    schemaId: String(parent.schemaId || ''),
+    currentSchemaId: String(parent.currentSchemaId || ''),
+    currentCreatedAt: String(parent.currentCreatedAt || ''),
+    createdAt: String(parent.createdAt || ''),
+    continuationTrace: String(parent.continuationTrace || ''),
+    boundary: String(parent.boundary || parent.source?.boundary || ''),
+    sourceMode: String(parent.sourceMode || ''),
+    recoveryMode: String(parent.recoveryMode || parent.parentRecoveryMode || ''),
+    source: parent.source || null,
+    markdown: String(parent.markdown || ''),
+    integrity: parent.integrity || null,
+    publishedReference: normalizeReferenceEvidence(parent.publishedReference || parent.browseGitReference || parent.browseGit || null),
+    schemaReferenceAuthority: normalizeSchemaReferenceEvidence(parent.schemaReferenceAuthority || parent.parentSchemaReferenceAuthority || null)
+  });
+}
+
+export function qualifyPortableExactParent(parent = {}, transitionType = 'create-artifact') {
+  const rootCreation = String(transitionType || 'create-artifact') === 'create-artifact';
+  const declared = parentHasAnyValue(parent);
+  if (rootCreation) return declared ? invalid('root-parent-declared') : qualified(Object.freeze({}));
+  if (!declared) return invalid('continuation-parent-required');
+  if (!parent.id) return invalid('continuation-parent-id-required');
+  const schemaAuthority = qualifyParentSchemaAuthority(parent);
+  if (schemaAuthority.state !== 'qualified') return invalid(schemaAuthority.reason, schemaAuthority.evidence);
+  if (!parent.path) return invalid('continuation-parent-origin-required');
+  const createdAtAuthority = qualifyParentCreatedAtAuthority(parent);
+  if (createdAtAuthority.state !== 'qualified') return invalid(createdAtAuthority.reason, createdAtAuthority.evidence);
+  if (parent.continuationTrace) return invalid('continuation-parent-legacy-trace-not-authority', { observedTrace: parent.continuationTrace });
+  const schemaReference = parent.schemaReferenceAuthority || {};
+  if (schemaReference.schemaId && schemaReference.schemaId !== schemaAuthority.schemaId) return invalid('continuation-parent-schema-reference-contradictory', { schemaId: schemaAuthority.schemaId, referenceSchemaId: schemaReference.schemaId });
+  const snapshot = Object.freeze({
+    ...parent,
+    schemaId: schemaAuthority.schemaId,
+    createdAt: createdAtAuthority.createdAt,
+    continuationTrace: ''
+  });
+  const schemaReferenceQualified = Boolean(schemaReference.preferredTarget && schemaReference.resolutionState === 'qualified');
+  const published = parent.publishedReference || {};
+  if (schemaReferenceQualified) return qualified(snapshot);
+  if (!schemaReferenceQualified) return qualifiedLocal(snapshot, 'continuation-parent-schema-reference-unqualified', {
+    schemaReferenceAuthority: schemaReference,
+    publishedReference: published,
+    exactnessConflict: 'Local continuity can preserve the declared Parent Schema identity/reference, but exact continuation requires independently qualified Parent Schema authority.'
+  });
+}
+
+function qualifyParentCreatedAtAuthority(parent = {}) {
+  const declared = [
+    ...(parent.currentCreatedAt ? [{ field: 'currentCreatedAt', value: String(parent.currentCreatedAt) }] : []),
+    ...(parent.createdAt ? [{ field: 'createdAt', value: String(parent.createdAt) }] : [])
+  ];
+  const distinct = [...new Set(declared.map((item) => item.value))];
+  if (distinct.length > 1) return Object.freeze({ state: 'invalid', reason: 'continuation-parent-created-at-contradictory', createdAt: '', evidence: Object.freeze({ declared: Object.freeze(declared.map((item) => Object.freeze({ ...item }))) }) });
+  const createdAt = distinct[0] || '';
+  if (createdAt && !ROOT_TIMESTAMP_SHAPE.test(createdAt)) return Object.freeze({ state: 'invalid', reason: 'continuation-parent-created-at-invalid', createdAt: '', evidence: Object.freeze({ observedCreatedAt: createdAt, requiredShape: 'YYYY-MM-DD hh:mm:ss', declared: Object.freeze(declared.map((item) => Object.freeze({ ...item }))) }) });
+  return Object.freeze({ state: 'qualified', reason: '', createdAt, evidence: Object.freeze({ declared: Object.freeze(declared.map((item) => Object.freeze({ ...item }))) }) });
+}
+
+export function renderQualifiedPortableExactDraft({ contract = {}, schemaId = '', transitionType = 'create-artifact', parentSnapshot = {}, rendererInput = {} } = {}) {
+  const markdown = createArtifactDraftMarkdown(contract, { ...rendererInput, parentRecord: parentSnapshot, currentSchemaId: schemaId });
+  if (!markdown) return Object.freeze({ state: 'unqualified', reason: 'exact-renderer-empty-or-unqualified', markdown: '', validation: null, parentRepresentation: null });
+  const validation = validateArtifactCreationResult({ schemaId, status: 'local', sourceMode: 'local-portable-draft', markdown }, parentSnapshot, { contract, childPath: rendererInput.childPath || '', expectedAuthors: rendererInput.authors });
+  const parentRepresentation = qualifyPortableRenderedParentRepresentation(markdown, parentSnapshot, transitionType, rendererInput.childPath || '');
+  if (!validation.ok) return Object.freeze({ state: 'unqualified', reason: 'exact-result-validation-failed', markdown: '', validation, parentRepresentation });
+  if (parentRepresentation.state !== 'qualified') return Object.freeze({ state: 'unqualified', reason: parentRepresentation.reason, markdown: '', validation, parentRepresentation });
+  return Object.freeze({ state: 'qualified', reason: '', markdown, validation, parentRepresentation });
+}
+
+export function renderPortableLocalContinuityDraft({ contract = {}, schemaId = '', transitionType = 'continue-from-record', parentSnapshot = {}, rendererInput = {} } = {}) {
+  const markdown = renderArtifactCreationCandidateMarkdown(contract, { ...rendererInput, parentRecord: parentSnapshot, currentSchemaId: schemaId });
+  if (!markdown) return Object.freeze({ state: 'unqualified', reason: 'local-continuity-renderer-empty', markdown: '', validation: null, parentRepresentation: null });
+  const parentRepresentation = qualifyPortableRenderedParentRepresentation(markdown, parentSnapshot, transitionType, rendererInput.childPath || '', { allowUnpublishedLocalParent: true });
+  if (parentRepresentation.state !== 'qualified') return Object.freeze({ state: 'unqualified', reason: parentRepresentation.reason || 'local-continuity-parent-representation-mismatch', markdown: '', validation: null, parentRepresentation });
+  const validation = validateArtifactCreationResult({ schemaId, status: 'local', sourceMode: 'local-portable-draft', markdown }, parentSnapshot, { contract, childPath: rendererInput.childPath || '', expectedAuthors: rendererInput.authors });
+  return Object.freeze({
+    state: 'qualified-local-continuity',
+    reason: 'continuation-parent-browse-git-root-contract-conflict',
+    markdown,
+    validation,
+    parentRepresentation
+  });
+}
+
+function qualifyParentSchemaAuthority(parent = {}) {
+  const schemaId = String(parent.schemaId || '');
+  const currentSchemaId = String(parent.currentSchemaId || '');
+  const declared = [...(schemaId ? [{ field: 'schemaId', value: schemaId }] : []), ...(currentSchemaId ? [{ field: 'currentSchemaId', value: currentSchemaId }] : [])];
+  if (!declared.length) return Object.freeze({ state: 'invalid', reason: 'continuation-parent-schema-required', schemaId: '', evidence: Object.freeze({}) });
+  const distinct = [...new Set(declared.map((item) => item.value))];
+  if (distinct.length !== 1) return Object.freeze({ state: 'invalid', reason: 'continuation-parent-schema-contradictory', schemaId: '', evidence: Object.freeze({ schemaId, currentSchemaId, declared: Object.freeze(declared.map((item) => Object.freeze({ ...item }))) }) });
+  return Object.freeze({ state: 'qualified', reason: '', schemaId: distinct[0], evidence: Object.freeze({ declared: Object.freeze(declared.map((item) => Object.freeze({ ...item }))) }) });
+}
+
+export function qualifyPortableRenderedParentRepresentation(markdown = '', parent = {}, transitionType = 'create-artifact', childPath = '', options = {}) {
+  const rootCreation = String(transitionType || 'create-artifact') === 'create-artifact';
+  let parsed;
+  try { parsed = parseArtifactMarkdown(markdown); } catch (_) { return Object.freeze({ state: 'invalid', reason: 'exact-result-parent-parse-failed' }); }
+  const observed = parsed.envelope?.parent || {};
+  const hasObserved = Boolean(observed.schema?.id || observed.trace || observed.origin || observed.createdAt || observed.boundary || observed.originEntries?.length);
+  if (rootCreation) return Object.freeze({ state: hasObserved ? 'invalid' : 'qualified', reason: hasObserved ? 'exact-result-parent-unexpected' : '' });
+  const relative = relativePath(dirname(childPath), parent.path);
+  const published = parent.publishedReference || {};
+  const publishedTarget = String(published.target || '');
+  const publishedQualified = Boolean(publishedTarget && published.state === 'qualified');
+  const recoveryMode = String(parent.recoveryMode || '').trim() === 'external-versioned' ? 'external-versioned' : 'local-relative';
+  const schemaTarget = String(parent.schemaReferenceAuthority?.preferredTarget || '');
+  const origins = observed.originEntries || [];
+  const createdAtLines = renderedParentFieldLines(markdown, 'Created At');
+  const expectedCreatedAt = String(parent.createdAt || '');
+  const createdAtExact = expectedCreatedAt ? createdAtLines.length === 1 && createdAtLines[0] === `  - Created At: ${expectedCreatedAt}` : createdAtLines.length === 0;
+  const relativeOrigins = origins.filter((entry) => entry.label === 'relative');
+  const browseOrigins = origins.filter((entry) => entry.label === 'browse + git');
+  const expectedTrace = recoveryMode === 'external-versioned' ? publishedTarget : relative;
+  const baseExact = String(observed.schema?.id || '') === String(parent.schemaId || '')
+    && String(observed.schema?.target || '') === schemaTarget
+    && String(observed.trace || '') === expectedTrace
+    && /^\[[^\]]+\]\([^)]+\)$/.test(String(observed.traceRaw || ''))
+    && !String(observed.boundary || '')
+    && createdAtExact
+    && String(observed.createdAt || '') === expectedCreatedAt;
+  const exactOrigins = recoveryMode === 'external-versioned'
+    ? publishedQualified && relativeOrigins.length === 0 && browseOrigins.length === 1 && browseOrigins[0].target === publishedTarget && origins.length === 1
+    : relativeOrigins.length === 1 && relativeOrigins[0].target === relative && (publishedQualified
+      ? browseOrigins.length === 1 && browseOrigins[0].target === publishedTarget && origins.length === 2
+      : browseOrigins.length === 0 && origins.length === 1);
+  const exact = baseExact && exactOrigins;
+  return Object.freeze({
+    state: exact ? 'qualified' : 'invalid',
+    reason: exact ? '' : 'exact-result-parent-representation-mismatch',
+    expected: Object.freeze({ schemaId: String(parent.schemaId || ''), schemaTarget, recoveryMode, trace: expectedTrace, relativeOrigin: recoveryMode === 'external-versioned' ? '' : relative, browseGitOrigin: publishedQualified ? publishedTarget : '', createdAt: expectedCreatedAt }),
+    observed: Object.freeze({ schemaId: String(observed.schema?.id || ''), schemaTarget: String(observed.schema?.target || ''), trace: String(observed.trace || ''), traceRaw: String(observed.traceRaw || ''), origins: Object.freeze(origins), boundary: String(observed.boundary || ''), createdAt: String(observed.createdAt || ''), createdAtLines: Object.freeze(createdAtLines) })
+  });
+}
+
+function renderedParentFieldLines(markdown = '', label = '') {
+  const lines = String(markdown || '').split('\n');
+  const start = lines.findIndex((line) => line === '- Parent');
+  if (start < 0) return [];
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) if (/^-\s+\S/.test(lines[i])) { end = i; break; }
+  const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`^  - ${escaped}:`);
+  return lines.slice(start + 1, end).filter((line) => re.test(line));
+}
+
+function normalizeReferenceEvidence(value) {
+  if (!value) return Object.freeze({ target: '', state: 'unavailable', evidence: Object.freeze({}) });
+  if (typeof value === 'string') return Object.freeze({ target: value, state: 'unresolved', evidence: Object.freeze({}) });
+  return Object.freeze({ target: String(value.target || value.url || ''), state: String(value.state || value.resolutionState || 'unresolved'), evidence: Object.freeze({ ...(value.evidence || value.resolutionEvidence || {}) }) });
+}
+function normalizeSchemaReferenceEvidence(value) {
+  if (!value) return Object.freeze({ schemaId: '', preferredTarget: '', exactTargets: Object.freeze([]), resolutionState: 'unavailable', evidence: Object.freeze({}) });
+  if (typeof value === 'string') return Object.freeze({ schemaId: '', preferredTarget: value, exactTargets: Object.freeze([value]), resolutionState: 'unresolved', evidence: Object.freeze({}) });
+  const preferredTarget = String(value.preferredTarget || value.target || '');
+  return Object.freeze({ schemaId: String(value.schemaId || ''), preferredTarget, exactTargets: Object.freeze([...new Set([...(value.exactTargets || []), preferredTarget].map(String).filter(Boolean))]), resolutionState: String(value.resolutionState || value.state || 'unresolved'), evidence: Object.freeze({ ...(value.evidence || value.resolutionEvidence || {}) }) });
+}
+function parentHasAnyValue(parent = {}) { return Boolean(parent.id || parent.path || parent.kind || parent.schemaId || parent.currentSchemaId || parent.continuationTrace || parent.currentCreatedAt || parent.createdAt || parent.boundary || parent.sourceMode || parent.source || parent.publishedReference?.target || parent.schemaReferenceAuthority?.preferredTarget); }
+function qualified(snapshot) { return Object.freeze({ state: 'qualified', reason: '', snapshot }); }
+function qualifiedLocal(snapshot, reason = 'continuation-parent-browse-git-root-contract-conflict', evidence = {}) { return Object.freeze({ state: 'qualified-local-continuity', reason, snapshot, evidence: Object.freeze({ ...evidence }) }); }
+function invalid(reason, evidence = {}) { return Object.freeze({ state: 'invalid', reason, snapshot: null, evidence: Object.freeze({ ...evidence }) }); }
+function normalizePath(value='') { return String(value || '').replace(/\\/g,'/').replace(/^\.\//,'').replace(/^\/+|\/+$/g,''); }
+function dirname(value='') { const p=normalizePath(value); const i=p.lastIndexOf('/'); return i<0?'':p.slice(0,i); }
+function relativePath(fromDir='', toPath='') { const from=normalizePath(fromDir).split('/').filter(Boolean), to=normalizePath(toPath).split('/').filter(Boolean); let i=0; while(i<from.length&&i<to.length&&from[i]===to[i])i++; return [...Array(from.length-i).fill('..'),...to.slice(i)].join('/') || (to.at(-1)||''); }

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

@@ -0,0 +1,265 @@
+import { parseArtifactMarkdown } from '../../../artifacts/artifact.parse.js';
+import { runAudit } from '../../../audit/audit.run.js';
+import { createRecordFromMarkdown } from '../../../artifacts/artifact.record.js';
+import { portableFinding, normalizePortableFinding, summarizePortableFindings } from '../findings.js';
+import { selectPortableLoadedSchemaMaterial } from '../providers/schema.providers.js';
+import { buildPortableSchemaGuide } from '../schema/schema.guide.js';
+import { compilePortableSchemaContract } from '../schema/contract.compile.js';
+import { validatePortableContractInstance } from '../schema/contract.validate.js';
+import { portableRuntimeValidationContractForSchema } from '../schema/qualifiedLocalRoot.runtime.js';
+
+export function validatePortableDraft(input = {}, options = {}) {
+  const markdown = String(input.markdown || input.draft?.markdown || '');
+  const path = String(input.path || input.draft?.path || 'draft.md');
+  const requestedSchema = String(input.schemaId || options.schemaId || '').trim();
+  const findings = [];
+  if (!markdown) findings.push(portableFinding('error', 'portable.draft.markdown.required', 'Draft validation requires Markdown content.', { ref: path }));
+  const record = createRecordFromMarkdown(markdown, { path, name: path, sourceMode: 'portable-local-draft', lifecycleStatus: 'draft' });
+  const parsed = safeParse(markdown);
+  const declaredSchema = String(parsed.envelope?.current?.schema?.id || record.schemaId || '').trim();
+  const runtimeProjection = portableRuntimeValidationContractForSchema(requestedSchema || declaredSchema);
+  const audit = runAudit({ record, markdown, schemaReferenceAuthorities: input.schemaReferenceAuthorities || null, validationContractOverride: runtimeProjection.state === 'qualified' ? runtimeProjection.compiledContract : null });
+  if (requestedSchema && declaredSchema !== requestedSchema) findings.push(portableFinding('error', 'portable.draft.schema.mismatch', 'Draft Current Schema does not match the requested schema.', { requestedSchema, declaredSchema, ref: path }));
+  const sharedParserQuirks = detectSharedParserQuirks(markdown, parsed, audit, path);
+  const suppressedAuditCodes = new Set(sharedParserQuirks.flatMap((quirk) => quirk.suppressedCodes || []));
+  findings.push(...(audit.findings || [])
+    .filter((finding) => !suppressedAuditCodes.has(finding.code))
+    .map((finding) => normalizePortableFinding(finding, { ref: path })));
+  for (const quirk of sharedParserQuirks) findings.push(portableFinding('info', quirk.code, quirk.message, { ref: path, suppressedCodes: quirk.suppressedCodes, owner: quirk.owner }));
+  const schemaSelection = selectPortableLoadedSchemaMaterial(input.materials || input, { schemaId: requestedSchema || declaredSchema });
+  findings.push(...schemaSelection.findings);
+  const schemaMaterial = schemaSelection.material || null;
+  let structural = null;
+  if (audit.contractValidation?.available) {
+    structural = sharedContractValidationReceipt(audit.contractValidation, path);
+  } else if (schemaMaterial?.markdown) {
+    structural = validateContractStructure(markdown, schemaMaterial.markdown, requestedSchema || declaredSchema, path);
+    findings.push(...structural.findings);
+    if (structural.conditionalRequirements.length) findings.push(portableFinding('info', 'portable.draft.conditional-review.required', 'The readable schema contains conditional requirements that require trigger-aware review; they were not treated as unconditional failures.', {
+      schemaId: requestedSchema || declaredSchema,
+      groups: structural.conditionalRequirements.map((entry) => entry.name),
+      ref: path
+    }));
+  } else {
+    findings.push(portableFinding('info', 'portable.draft.contract-structure.unavailable', 'Readable child schema material was not supplied, so contract-driven structural validation was not run.', { schemaId: requestedSchema || declaredSchema, ref: path }));
+  }
+  const exactCreationValidation = input.exactCreationValidation || null;
+  const exactRuntimeValidation = Boolean(
+    exactCreationValidation?.ok === true
+    && runtimeProjection.state === 'qualified'
+    && !audit.resolution?.fallbackUsed
+    && typeof audit.resolution?.module?.validate === 'function'
+    && audit.status === 'readable'
+    && !findings.some((finding) => finding.code === 'audit.validator.unavailable')
+  );
+  const summary = summarizePortableFindings(findings);
+  return Object.freeze({
+    schema: 'tiinex.portable.draft-validation.v1',
+    path,
+    requestedSchema,
+    declaredSchema,
+    status: summary.counts.error ? 'invalid' : summary.counts.warning ? 'degraded' : 'clean',
+    audit: sanitizeAudit(audit),
+    sharedParserQuirks: Object.freeze(sharedParserQuirks),
+    structural,
+    qualification: Object.freeze({
+      exactRuntimeValidation,
+      contractDrivenStructuralValidation: Boolean(structural),
+      readableSchemaAvailable: Boolean(schemaMaterial),
+      fallbackUsed: Boolean(audit.resolution?.fallbackUsed),
+      limitations: Object.freeze([
+        ...(audit.resolution?.fallbackUsed ? ['Runtime audit used Root fallback and does not prove child-schema validity.'] : []),
+        ...(sharedParserQuirks.length ? ['The shared parser currently leaks Current.CreatedAt into Parent when no Parent block exists; raw audit findings are preserved, but parser-induced parent repair findings are excluded from portable repair guidance.'] : []),
+        ...(audit.contractValidation?.available ? ['Semantic contract validity was evaluated from the qualified current Root/descendant compiled machine-contract projection.'] : structural ? ['Only supplied readable-schema structural checks were available; complete current Root/descendant compiled contract authority was unavailable.'] : ['Readable schema contract was unavailable.']),
+        ...(!exactCreationValidation ? ['Exact canonical creation/reference/integrity validation evidence was not supplied; exactRuntimeValidation remains false.'] : [])
+      ])
+    }),
+    findings: Object.freeze(findings),
+    findingSummary: summary
+  });
+}
+
+export function explainPortableFindings(input = {}) {
+  const findings = extractFindings(input).map((finding) => normalizePortableFinding(finding));
+  const explanations = findings.map((finding) => Object.freeze({
+    severity: finding.severity,
+    code: finding.code,
+    message: finding.message,
+    blocking: finding.severity === 'error',
+    category: findingCategory(finding),
+    likelyOwner: findingOwner(finding),
+    recommendedAction: recommendedAction(finding),
+    preserveBoundary: boundaryWarning(finding)
+  }));
+  return Object.freeze({
+    schema: 'tiinex.portable.finding-explanation.v1',
+    explanations: Object.freeze(explanations),
+    findingSummary: summarizePortableFindings(findings)
+  });
+}
+
+export function buildPortableRepairPlan(input = {}) {
+  const explanation = explainPortableFindings(input);
+  const steps = [];
+  const seen = new Set();
+  for (const item of explanation.explanations) {
+    const key = `${item.category}:${item.recommendedAction}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    steps.push(Object.freeze({
+      order: steps.length + 1,
+      priority: item.blocking ? 'blocking' : item.severity === 'warning' ? 'important' : 'optional',
+      category: item.category,
+      action: item.recommendedAction,
+      codes: Object.freeze(explanation.explanations.filter((entry) => entry.category === item.category && entry.recommendedAction === item.recommendedAction).map((entry) => entry.code)),
+      constraint: item.preserveBoundary
+    }));
+  }
+  steps.sort((a, b) => priorityRank(a.priority) - priorityRank(b.priority) || a.order - b.order);
+  return Object.freeze({
+    schema: 'tiinex.portable.repair-plan.v1',
+    status: explanation.findingSummary.status,
+    steps: Object.freeze(steps.map((step, index) => Object.freeze({ ...step, order: index + 1 }))),
+    boundary: Object.freeze({
+      automaticRewrite: false,
+      preserveUnknownSections: true,
+      preserveSourceAndContinuity: true,
+      claimExactQualificationAfterRepair: false
+    }),
+    findingSummary: explanation.findingSummary
+  });
+}
+
+
+function detectSharedParserQuirks(markdown, parsed, audit, path) {
+  const quirks = [];
+  const parentBlockDeclared = /^-\s+Parent\s*$/m.test(String(markdown || ''));
+  const parent = parsed.envelope?.parent || {};
+  const current = parsed.envelope?.current || {};
+  const leakedCurrentCreatedAt = !parentBlockDeclared
+    && !parent.schema?.id
+    && !parent.trace
+    && !parent.origin
+    && Boolean(parent.createdAt)
+    && parent.createdAt === current.createdAt;
+  const parentWarningCodes = ['root.parent.schema.missing', 'root.parent.trace.missing', 'root.parent.origin.missing'];
+  const auditCodes = new Set((audit.findings || []).map((finding) => finding.code));
+  if (leakedCurrentCreatedAt && parentWarningCodes.some((code) => auditCodes.has(code))) {
+    quirks.push(Object.freeze({
+      code: 'portable.draft.shared-parser.parent-block-fallback',
+      message: 'The shared artifact parser treated Current.CreatedAt as Parent.CreatedAt because no Parent block was present. Portable repair guidance excludes the resulting parent warnings so an LLM is not encouraged to invent lineage.',
+      owner: 'src/artifacts/artifact.parse.js:blockAfterTopLevelList',
+      ref: path,
+      suppressedCodes: Object.freeze(parentWarningCodes.filter((code) => auditCodes.has(code)))
+    }));
+  }
+  return Object.freeze(quirks);
+}
+
+function validateContractStructure(draftMarkdown, schemaMarkdown, schemaId, path) {
+  const compiled = compilePortableSchemaContract(schemaMarkdown);
+  const validation = validatePortableContractInstance({ markdown: draftMarkdown, compiledContract: compiled });
+  const missingSections = validation.findings.filter((finding) => finding.code === 'portable.contract.section.required.missing').map((finding) => finding.section);
+  const missingFields = validation.findings.filter((finding) => finding.code === 'portable.contract.field.required.missing' || finding.code === 'portable.contract.declaration.field.required.missing').map((finding) => finding.field);
+  return Object.freeze({
+    schema: 'tiinex.portable.contract-structure-validation.v2',
+    schemaId,
+    status: validation.status,
+    requiredSections: compiled.validation.requiredSections,
+    requiredFields: compiled.validation.requiredFields,
+    missingSections: Object.freeze(missingSections),
+    missingFields: Object.freeze(missingFields),
+    conditionalRequirements: compiled.validation.conditionalRequirements,
+    compiledContractSchema: compiled.schema,
+    findings: Object.freeze(validation.findings.map((finding) => normalizePortableFinding(finding, { ref: path })))
+  });
+}
+
+function sanitizeAudit(audit = {}) {
+  return Object.freeze({
+    status: audit.status || '',
+    resolution: Object.freeze({
+      status: audit.resolution?.status || '',
+      moduleId: audit.resolution?.module?.id || audit.artifact?.moduleId || '',
+      fallbackUsed: Boolean(audit.resolution?.fallbackUsed || audit.artifact?.fallbackUsed),
+      unresolvedSchemaId: audit.resolution?.unresolvedSchemaId || ''
+    }),
+    summary: audit.summary || null,
+    validation: audit.validation || null,
+    findings: Object.freeze((audit.findings || []).map((finding) => normalizePortableFinding(finding)))
+  });
+}
+
+function sharedContractValidationReceipt(contractValidation = {}, path = '') {
+  const result = contractValidation.result || {};
+  return Object.freeze({
+    schema: 'tiinex.portable.contract-structure-validation.v3',
+    schemaId: contractValidation.schemaId || '',
+    status: result.status || contractValidation.state || 'unresolved',
+    authority: 'qualified-current-root-descendant-compiled-contract',
+    lineage: Object.freeze([...(contractValidation.lineage || [])]),
+    missingSections: Object.freeze((result.findings || []).filter((finding) => finding.code === 'portable.contract.section.required.missing').map((finding) => finding.section || '')),
+    missingFields: Object.freeze((result.findings || []).filter((finding) => String(finding.code || '').includes('field.required.missing')).map((finding) => finding.field || '')),
+    conditionalRequirements: Object.freeze([...(contractValidation.conditionalRequirements || [])].map((entry) => Object.freeze({ ...entry, name: entry.name || entry.group || '' }))),
+    findings: Object.freeze((result.findings || []).map((finding) => normalizePortableFinding(finding, { ref: path })))
+  });
+}
+
+function extractFindings(input = {}) {
+  if (Array.isArray(input)) return input;
+  if (Array.isArray(input.findings)) return input.findings;
+  if (Array.isArray(input.audit?.findings)) return input.audit.findings;
+  if (Array.isArray(input.validation?.findings)) return input.validation.findings;
+  return [];
+}
+
+function findingCategory(finding = {}) {
+  const code = String(finding.code || '').toLowerCase();
+  if (code.includes('schema')) return 'schema';
+  if (code.includes('parent') || code.includes('trace') || code.includes('lineage')) return 'continuity';
+  if (code.includes('origin') || code.includes('source') || code.includes('boundary')) return 'provenance';
+  if (code.includes('integrity') || code.includes('checksum')) return 'integrity';
+  if (code.includes('section') || code.includes('field') || code.includes('shape')) return 'structure';
+  return 'content-or-policy';
+}
+
+function findingOwner(finding = {}) {
+  const category = findingCategory(finding);
+  if (category === 'schema') return 'schema selection or schema companion';
+  if (category === 'continuity') return 'artifact continuity envelope';
+  if (category === 'provenance') return 'artifact origin/source boundary';
+  if (category === 'integrity') return 'integrity generation/verification tooling';
+  if (category === 'structure') return 'artifact body writer';
+  return 'human or LLM writer with schema guidance';
+}
+
+function recommendedAction(finding = {}) {
+  const category = findingCategory(finding);
+  if (category === 'schema') return 'Confirm the intended schema and obtain its readable canonical contract before rewriting the body.';
+  if (category === 'continuity') return 'Repair only the declared Parent/Trace/continuity fields using known loaded material; do not invent a parent.';
+  if (category === 'provenance') return 'State the known origin/source boundary explicitly and preserve unknown or local status.';
+  if (category === 'integrity') return 'Regenerate integrity only with the maintained integrity tool after content is final.';
+  if (category === 'structure') return 'Add or correct the named required section/field without removing unknown supplied content.';
+  return 'Review the relevant schema rule and make the smallest local change that resolves the finding.';
+}
+
+function boundaryWarning(finding = {}) {
+  const category = findingCategory(finding);
+  if (category === 'continuity') return 'Never guess a parent or convert Origin into Parent.';
+  if (category === 'provenance') return 'Never infer GitHub/source-backed status for local material.';
+  if (category === 'integrity') return 'Do not hand-edit integrity values.';
+  return 'Preserve unknown sections and unrelated content.';
+}
+
+function priorityRank(value = '') {
+  return value === 'blocking' ? 0 : value === 'important' ? 1 : 2;
+}
+
+function normalizeKey(value = '') {
+  return String(value || '').toLowerCase().replace(/[`*_#]/g, '').replace(/[^a-z0-9]+/g, ' ').trim();
+}
+
+function safeParse(markdown = '') {
+  try { return parseArtifactMarkdown(markdown); }
+  catch { return { envelope: {} }; }
+}

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

@@ -0,0 +1,45 @@
+export function buildPortableCreationQualification({ exactContract, exactRendererApplied, localContinuityRendererApplied = false, exactRendererParentCompatible, localContinuityParentCompatible = false, exactResultQualification, exactParentQualification, hasDeclaredParent, hasCompleteParent, schemaMaterial, validation, allowIncomplete, blocked }) {
+  const exactAvailable = exactContract.status === 'ready';
+  return Object.freeze({
+    blocked,
+    exactCreateTooling: Boolean(exactRendererApplied),
+    exactCreateToolingAvailable: exactAvailable,
+    exactCreateToolingApplied: Boolean(exactRendererApplied),
+    exactCreationResultQualification: String(exactResultQualification?.state || (exactRendererApplied ? 'qualified' : 'not-run')),
+    parentAuthorityQualification: String(exactParentQualification?.state || 'unqualified'),
+    parentAuthorityReason: String(exactParentQualification?.reason || ''),
+    localContinuityUsable: Boolean(localContinuityRendererApplied),
+    localContinuityAuthorityConflict: Boolean(localContinuityRendererApplied && localContinuityParentCompatible),
+    readableChildSchema: Boolean(schemaMaterial),
+    creationMode: exactRendererApplied
+      ? 'exact-site-creation-contract'
+      : localContinuityRendererApplied
+        ? 'local-relative-continuity-authority-conflict'
+        : schemaMaterial
+          ? hasCompleteParent ? 'llm-writer-from-readable-schema' : 'readable-schema-root-writer'
+          : 'unavailable',
+    exactRuntimeValidation: Boolean(validation?.qualification?.exactRuntimeValidation),
+    contractDrivenStructuralValidation: Boolean(validation?.qualification?.contractDrivenStructuralValidation),
+    incompleteDraftAllowed: allowIncomplete,
+    remoteWrite: false,
+    sourceMutation: false,
+    limitations: Object.freeze([
+      ...(!exactAvailable ? ['Exact child creation renderer is unavailable; the draft was rendered from readable schema structure and remains partially qualified.'] : []),
+      ...(exactAvailable && !exactRendererApplied && !hasDeclaredParent ? ['The exact shared renderer was available but could not be applied at the requested continuity mode; portable tooling did not invent a Parent or alternate creation semantics.'] : []),
+      ...(localContinuityRendererApplied ? [`Local continuity is represented with exact relative Trace and labeled relative Origin, while exact Parent qualification remains unresolved (${exactParentQualification?.reason || 'parent-authority-unresolved'}). No missing publication or reference authority is fabricated.`] : []),
+      ...(exactAvailable && !exactRendererParentCompatible && hasDeclaredParent && !localContinuityParentCompatible ? [`The supplied Parent is not qualified for exact continuation (${exactParentQualification?.reason || 'parent-unqualified'}); portable tooling did not rewrite or synthesize Parent identity.`] : []),
+      ...(hasDeclaredParent && !hasCompleteParent ? ['The supplied Parent declaration was incomplete and draft creation was blocked rather than inventing missing continuity or provenance fields.'] : []),
+      ...(validation?.qualification?.limitations || []),
+      ...(allowIncomplete ? ['Incomplete placeholders may remain and must not be treated as a qualified artifact.'] : [])
+    ])
+  });
+}
+
+
+export function portableParentRecordHasAnyValue(parent = {}) {
+  return Boolean(parent.id || parent.path || parent.kind || parent.schemaId || parent.currentSchemaId || parent.continuationTrace || parent.currentCreatedAt || parent.createdAt || parent.boundary || parent.sourceMode || parent.source || parent.publishedReference?.target || parent.schemaReferenceAuthority?.preferredTarget);
+}
+
+export function portableParentRecordIsComplete(parent = {}) {
+  return Boolean((parent.schemaId || parent.currentSchemaId) && (parent.continuationTrace || parent.id) && parent.path);
+}