@withtruing/companion 0.13.2 → 0.14.0

package/dist/whole-read/prd-build.js

@@ -0,0 +1,279 @@
+import { redactCanonicalText } from './redaction.js';
+import { WHOLE_READ_PHASE_POLICY } from './phase-policy.js';
+export const WHOLE_READ_PRD_CAPABILITY = 'whole-read-prd@1';
+export const WHOLE_READ_PRD_UNIT_PROTOCOL = 'whole-read-prd-unit@2';
+export const PRD_SOURCE_NOTICE = 'From the PRD — not yet checked against the code';
+const citationSchema = {
+    type: 'object', additionalProperties: false,
+    required: ['sectionId', 'quote'],
+    properties: { sectionId: { type: 'string', minLength: 1 },
+        quote: { type: 'string', minLength: 1, maxLength: 300 } },
+};
+const laneSchema = {
+    type: 'object', additionalProperties: false, required: ['key', 'label', 'citation'],
+    properties: { key: { type: 'string', minLength: 1 }, label: { type: 'string', minLength: 1 },
+        citation: { ...citationSchema, type: ['object', 'null'] } },
+};
+const claimSchema = {
+    type: 'object', additionalProperties: false,
+    required: ['claimId', 'laneKey', 'text', 'citations', 'status', 'statusCitation', 'verdict'],
+    properties: { claimId: { type: 'string', minLength: 1 }, laneKey: { type: 'string', minLength: 1 },
+        text: { type: 'string' }, citations: { type: 'array', minItems: 1, items: citationSchema },
+        status: { type: 'string', enum: ['shipped', 'in_progress', 'planned', 'proposed', 'unset'] },
+        statusCitation: { ...citationSchema, type: ['object', 'null'] },
+        verdict: { type: 'string', enum: ['pending', 'supported', 'contradicted', 'not_established'] } },
+};
+/** One registered strict schema is passed directly by every PRD model adapter. */
+export const prdUnitResultSchema = {
+    type: 'object', additionalProperties: false,
+    required: ['phase', 'lanes', 'claims', 'unmatchedSectionIds'],
+    properties: { phase: { type: 'string', enum: ['lanes', 'draft', 'check'] },
+        lanes: { type: 'array', items: laneSchema }, claims: { type: 'array', items: claimSchema },
+        unmatchedSectionIds: { type: 'array', items: { type: 'string', minLength: 1 } } },
+};
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const exact = (value, keys) => record(value) && Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+const nonBlank = (value) => typeof value === 'string' && value.trim().length > 0;
+const integer = (value) => Number.isSafeInteger(value) && Number(value) >= 0;
+const citationKey = (value) => JSON.stringify([value.sectionId, value.startChar, value.endChar]);
+function fragmentMap(fragment) {
+    const deliveredLength = Array.from(fragment.text).length;
+    if (!nonBlank(fragment.sectionId) || !integer(fragment.startChar) || !integer(fragment.endChar)
+        || fragment.endChar <= fragment.startChar)
+        throw new TypeError('prd_citation_invalid');
+    if (fragment.sourceMap === undefined) {
+        if (fragment.endChar - fragment.startChar !== deliveredLength)
+            throw new TypeError('prd_citation_invalid');
+        return [{ kind: 'source', deliveredStart: 0, deliveredEnd: deliveredLength,
+                sourceStartChar: fragment.startChar, sourceEndChar: fragment.endChar }];
+    }
+    let delivered = 0;
+    let source = fragment.startChar;
+    for (const segment of fragment.sourceMap) {
+        if (!exact(segment, ['kind', 'deliveredStart', 'deliveredEnd', 'sourceStartChar', 'sourceEndChar'])
+            || !['source', 'replacement'].includes(String(segment.kind))
+            || !integer(segment.deliveredStart) || !integer(segment.deliveredEnd)
+            || !integer(segment.sourceStartChar) || !integer(segment.sourceEndChar)
+            || segment.deliveredStart !== delivered || segment.sourceStartChar !== source
+            || segment.deliveredEnd <= segment.deliveredStart || segment.sourceEndChar <= segment.sourceStartChar
+            || (segment.kind === 'source'
+                && segment.deliveredEnd - segment.deliveredStart !== segment.sourceEndChar - segment.sourceStartChar)) {
+            throw new TypeError('prd_citation_invalid');
+        }
+        delivered = segment.deliveredEnd;
+        source = segment.sourceEndChar;
+    }
+    if (delivered !== deliveredLength || source !== fragment.endChar)
+        throw new TypeError('prd_citation_invalid');
+    return fragment.sourceMap;
+}
+function pointMatches(haystack, needle) {
+    const matches = [];
+    for (let start = 0; start + needle.length <= haystack.length; start += 1) {
+        if (needle.every((point, offset) => haystack[start + offset] === point)) {
+            matches.push({ start, end: start + needle.length });
+        }
+    }
+    return matches;
+}
+function normalized(value) {
+    const original = Array.from(value);
+    const points = [];
+    const spans = [];
+    for (let index = 0; index < original.length;) {
+        const start = index;
+        const whitespace = /\s/u.test(original[index]);
+        index += 1;
+        if (whitespace)
+            while (index < original.length && /\s/u.test(original[index]))
+                index += 1;
+        points.push(whitespace ? ' ' : original[start]);
+        spans.push({ start, end: index });
+    }
+    return { points, spans };
+}
+function canonicalSpan(fragment, deliveredStart, deliveredEnd) {
+    const relevant = fragmentMap(fragment).filter((segment) => segment.deliveredEnd > deliveredStart && segment.deliveredStart < deliveredEnd);
+    if (!relevant.length)
+        throw new TypeError('prd_citation_invalid');
+    const first = relevant[0];
+    const last = relevant.at(-1);
+    const startChar = first.kind === 'source'
+        ? first.sourceStartChar + deliveredStart - first.deliveredStart : first.sourceStartChar;
+    const endChar = last.kind === 'source'
+        ? last.sourceStartChar + deliveredEnd - last.deliveredStart : last.sourceEndChar;
+    if (startChar < fragment.startChar || endChar > fragment.endChar || endChar <= startChar) {
+        throw new TypeError('prd_citation_invalid');
+    }
+    return { sectionId: fragment.sectionId, startChar, endChar };
+}
+function citation(value, fragments) {
+    if (!exact(value, ['sectionId', 'quote']) || !nonBlank(value.sectionId) || !nonBlank(value.quote)
+        || Array.from(value.quote).length > 300)
+        throw new TypeError('prd_citation_invalid');
+    const candidates = fragments.filter((fragment) => fragment.sectionId === value.sectionId);
+    if (!candidates.length)
+        throw new TypeError('prd_citation_invalid');
+    const quote = Array.from(value.quote);
+    const exactMatches = candidates.flatMap((fragment) => pointMatches(Array.from(fragment.text), quote).map((match) => ({ fragment, ...match })));
+    if (exactMatches.length > 1)
+        throw new TypeError('prd_citation_invalid');
+    if (exactMatches.length === 1)
+        return canonicalSpan(exactMatches[0].fragment, exactMatches[0].start, exactMatches[0].end);
+    const normalizedQuote = normalized(value.quote).points;
+    const normalizedMatches = candidates.flatMap((fragment) => {
+        const text = normalized(fragment.text);
+        return pointMatches(text.points, normalizedQuote).map((match) => ({ fragment,
+            start: text.spans[match.start].start, end: text.spans[match.end - 1].end }));
+    });
+    if (normalizedMatches.length !== 1)
+        throw new TypeError('prd_citation_invalid');
+    return canonicalSpan(normalizedMatches[0].fragment, normalizedMatches[0].start, normalizedMatches[0].end);
+}
+function excerpt(value, fragments) {
+    const fragment = fragments.find((item) => item.sectionId === value.sectionId
+        && value.startChar >= item.startChar && value.endChar <= item.endChar);
+    if (!fragment)
+        throw new TypeError('prd_citation_invalid');
+    const relevant = fragmentMap(fragment).filter((segment) => segment.sourceEndChar > value.startChar && segment.sourceStartChar < value.endChar);
+    if (!relevant.length)
+        throw new TypeError('prd_citation_invalid');
+    const first = relevant[0];
+    const last = relevant.at(-1);
+    const start = first.kind === 'source'
+        ? first.deliveredStart + value.startChar - first.sourceStartChar : first.deliveredStart;
+    const end = last.kind === 'source'
+        ? last.deliveredStart + value.endChar - last.sourceStartChar : last.deliveredEnd;
+    return Array.from(fragment.text).slice(start, end).join('');
+}
+function explicitDivision(value, fragments) {
+    return /\b(audience|persona|product|customers?|users?|admins?|merchants?|operators?|teams?)\b/i.test(excerpt(value, fragments));
+}
+function explicitStatus(status, value, fragments) {
+    const text = excerpt(value, fragments);
+    const patterns = {
+        shipped: /\b(shipped|released|live|already built)\b/i,
+        in_progress: /\b(in progress|being built|under development)\b/i,
+        planned: /\b(planned|not yet built|scheduled|for q[1-4])\b/i,
+        proposed: /\b(proposed|proposal|candidate)\b/i,
+    };
+    return status !== 'unset' && patterns[status].test(text);
+}
+function parsedClaim(value, unit) {
+    if (!exact(value, ['claimId', 'laneKey', 'text', 'citations', 'status', 'statusCitation', 'verdict'])
+        || !nonBlank(value.claimId) || !nonBlank(value.laneKey) || typeof value.text !== 'string'
+        || !Array.isArray(value.citations) || value.citations.length === 0
+        || !['shipped', 'in_progress', 'planned', 'proposed', 'unset'].includes(String(value.status))
+        || !['pending', 'supported', 'contradicted', 'not_established'].includes(String(value.verdict))) {
+        throw new TypeError('prd_citation_invalid');
+    }
+    const citations = value.citations.map((item) => citation(item, unit.fragments));
+    const status = value.status;
+    const statusCitation = value.statusCitation === null ? null : citation(value.statusCitation, unit.fragments);
+    if ((status === 'unset') !== (statusCitation === null)
+        || (statusCitation && (!citations.some((item) => citationKey(item) === citationKey(statusCitation))
+            || !explicitStatus(status, statusCitation, unit.fragments))))
+        throw new TypeError('prd_citation_invalid');
+    return { claimId: value.claimId, laneKey: value.laneKey, text: value.text,
+        citations, status, statusCitation, verdict: value.verdict };
+}
+export function validatePrdUnitResult(unit, value) {
+    if (!exact(value, ['phase', 'lanes', 'claims', 'unmatchedSectionIds']) || value.phase !== unit.phase
+        || !Array.isArray(value.lanes) || !Array.isArray(value.claims) || !Array.isArray(value.unmatchedSectionIds)
+        || value.unmatchedSectionIds.some((id) => !nonBlank(id)))
+        throw new TypeError('prd_citation_invalid');
+    let lanes = [];
+    if (unit.phase === 'lanes') {
+        if (value.claims.length || value.unmatchedSectionIds.length)
+            throw new TypeError('prd_citation_invalid');
+        lanes = value.lanes.map((candidate) => {
+            if (!exact(candidate, ['key', 'label', 'citation']) || !nonBlank(candidate.key)
+                || !nonBlank(candidate.label) || candidate.citation === null)
+                throw new TypeError('prd_citation_invalid');
+            const cited = citation(candidate.citation, unit.fragments);
+            if (!explicitDivision(cited, unit.fragments))
+                throw new TypeError('prd_citation_invalid');
+            return { key: candidate.key, label: candidate.label, citation: cited };
+        });
+        if (!lanes.length)
+            lanes = [{ key: 'document', label: 'Document', citation: null }];
+        if (new Set(lanes.map((lane) => lane.key)).size !== lanes.length)
+            throw new TypeError('prd_citation_invalid');
+        return { phase: unit.phase, lanes, claims: [], unmatchedSectionIds: [] };
+    }
+    if (value.lanes.length)
+        throw new TypeError('prd_citation_invalid');
+    const claims = value.claims.map((candidate) => parsedClaim(candidate, unit));
+    const unmatched = [...new Set(value.unmatchedSectionIds)];
+    const expected = new Set(unit.fragments.map((fragment) => fragment.sectionId));
+    const accounted = new Set([...claims.flatMap((claim) => claim.citations.map((item) => item.sectionId)), ...unmatched]);
+    if (expected.size !== accounted.size || [...expected].some((id) => !accounted.has(id))
+        || [...accounted].some((id) => !expected.has(id)))
+        throw new TypeError('prd_citation_invalid');
+    if (unit.phase === 'draft') {
+        if (claims.some((claim) => claim.verdict !== 'pending'
+            || !unit.lanes.some((lane) => lane.key === claim.laneKey)))
+            throw new TypeError('prd_citation_invalid');
+    }
+    else {
+        const candidates = new Map(unit.claims.map((claim) => [claim.claimId, claim]));
+        if (claims.length !== candidates.size || claims.some((claim) => {
+            const prior = candidates.get(claim.claimId);
+            return !prior || claim.verdict === 'pending' || claim.text !== prior.text || claim.laneKey !== prior.laneKey
+                || claim.citations.length !== prior.citations.length
+                || claim.citations.some((item, index) => citationKey(item) !== citationKey(prior.citations[index]));
+        }))
+            throw new TypeError('prd_citation_invalid');
+    }
+    return { phase: unit.phase, lanes: [], claims, unmatchedSectionIds: unmatched.sort() };
+}
+export function createPrdPrompt(unit) {
+    if (unit.protocolVersion !== WHOLE_READ_PRD_UNIT_PROTOCOL || unit.source.kind !== 'prd'
+        || !/^sha256:[0-9a-f]{64}$/.test(unit.source.textSha256)
+        || !Number.isSafeInteger(unit.outputTokens) || unit.outputTokens < 1)
+        throw new TypeError('prd_source_mismatch');
+    unit.fragments.forEach(fragmentMap);
+    const instruction = unit.phase === 'lanes'
+        ? 'Return only explicit product or audience divisions with citations; return no lanes when none are stated.'
+        : unit.phase === 'draft'
+            ? 'Draft faithful intent claims. Account for every section with a cited claim or unmatchedSectionIds. Do not infer status.'
+            : 'Check every candidate only against its cited PRD text. Preserve citations and abstain when unsupported.';
+    const cite = (item) => ({ sectionId: item.sectionId, quote: excerpt(item, unit.fragments) });
+    return `${instruction}\nCite by section id plus an exact short quote copied from that section's text. `
+        + `Use 1 to 300 characters and enough text to be unique within the section.\n`
+        + `Schema:${JSON.stringify(prdUnitResultSchema)}\nInput:${JSON.stringify({
+            phase: unit.phase, source: unit.source,
+            fragments: unit.fragments.map((fragment) => ({ sectionId: fragment.sectionId, text: fragment.text })),
+            lanes: unit.lanes.map((lane) => ({ key: lane.key, label: lane.label })),
+            claims: unit.claims.map((claim) => ({ ...claim, citations: claim.citations.map(cite),
+                statusCitation: claim.statusCitation && cite(claim.statusCitation) })),
+            unmatchedSectionIds: unit.unmatchedSectionIds,
+        })}`;
+}
+export function redactPrdFragment(fragment) {
+    const sourcePoints = Array.from(fragment.text);
+    if (fragment.endChar - fragment.startChar !== sourcePoints.length)
+        throw new TypeError('prd_citation_invalid');
+    const redacted = redactCanonicalText({ text: fragment.text });
+    const byteOffsets = [0];
+    for (const point of sourcePoints)
+        byteOffsets.push(byteOffsets.at(-1) + Buffer.byteLength(point));
+    const characterByByte = new Map(byteOffsets.map((byte, index) => [byte, fragment.startChar + index]));
+    const characterAtByte = (byte) => {
+        const index = characterByByte.get(byte);
+        if (index === undefined)
+            throw new TypeError('prd_citation_invalid');
+        return index;
+    };
+    return { ...fragment, text: redacted.text, sourceMap: redacted.mapping.segments.map((segment) => ({
+            kind: segment.kind, deliveredStart: segment.deliveredStart, deliveredEnd: segment.deliveredEnd,
+            sourceStartChar: characterAtByte(segment.canonicalStartByte),
+            sourceEndChar: characterAtByte(segment.canonicalEndByte),
+        })) };
+}
+export async function runPrdUnit(unit, model, signal, backend) {
+    const response = await backend({ prompt: createPrdPrompt(unit), schema: prdUnitResultSchema,
+        model, phase: `prd_${unit.phase}`,
+        maxTokens: WHOLE_READ_PHASE_POLICY[`prd_${unit.phase}`].maxOutputTokens, signal });
+    return { ...response, result: validatePrdUnitResult(unit, response.result) };
+}

package/dist/whole-read/prd-fidelity.js

@@ -0,0 +1,14 @@
+export const PRD_FIDELITY_POLICY_VERSION = 'prd-fidelity@1';
+export const PRD_NOT_CHECKED_LABEL = 'From the PRD — not yet checked against the code';
+const sourceMetadata = () => ({ codeChecked: false, sourceNotice: PRD_NOT_CHECKED_LABEL });
+/** Status is data from the checked passage, never a phase/list-order heuristic. */
+export function prdBoardMetadata(input = {}) {
+    const checked = input.checkedStatusPassage ?? null;
+    return {
+        status: checked?.status ?? 'unset',
+        statusEvidenceId: checked?.evidenceId ?? null,
+        statusCitation: checked?.citedPrdRange ?? null,
+        card: sourceMetadata(),
+        lane: sourceMetadata(),
+    };
+}