@protoyard/blueprint 0.0.0-stage → 1.1.1

package/dist/brief/kind-detection.js

@@ -0,0 +1,353 @@
+/**
+ * Brief kind detection (ADR-036): decides whether a prose brief asks for an
+ * app, a deck, a page or a doc before any app archetype is scored.
+ *
+ * The rules are deliberately conservative, because `app` is what every brief
+ * meant before kinds existed:
+ *
+ * 1. An explicit kind always wins.
+ * 2. A content kind is chosen only on a strong cue ("slides", "keynote",
+ *    "landing page", "report", "one-pager"…). Weak cues ("talk", "hero",
+ *    "article") are reported as a suggestion but never switch the kind.
+ * 3. A cue followed by a tool noun ("slide deck builder", "report generator")
+ *    describes an app that makes that content, so it counts for `app`.
+ * 4. Strong cues for two content kinds, or an app noun ("app", "dashboard",
+ *    "platform"…) before the first strong cue, make the brief ambiguous: the
+ *    result is `app`, with a reason that names the conflict and how to pick.
+ *
+ * Matching is on whole lowercase words (`normalize`), longest phrase first,
+ * so the same brief always gives the same result.
+ */
+import { BLUEPRINT_KINDS, DEFAULT_BLUEPRINT_KIND, isBlueprintKind, unknownKindMessage, } from "../kinds/kind.js";
+import { MAX_BRIEF_LENGTH } from "./limits.js";
+import { normalize } from "./text.js";
+/** Briefs longer than this are read up to the limit (matches `MAX_BRIEF_LENGTH`). */
+const MAX_DETECTION_LENGTH = MAX_BRIEF_LENGTH;
+/** Content cues per kind, in normalized words ("one-pager" normalizes to "one pager"). */
+export const KIND_CUES = {
+    deck: {
+        strong: [
+            'slides',
+            'slide deck',
+            'slide decks',
+            'slideshow',
+            'slide show',
+            'deck',
+            'decks',
+            'pitch deck',
+            'keynote',
+            'presentation',
+            'presentations',
+            'powerpoint',
+        ],
+        weak: [
+            'slide',
+            'talk',
+            'pitch',
+            'qbr',
+            'webinar',
+            'lecture',
+            'all hands',
+            'town hall',
+            'demo day',
+        ],
+    },
+    page: {
+        strong: [
+            'landing page',
+            'landing pages',
+            'one page site',
+            'one page website',
+            'single page site',
+            'single page website',
+            'marketing page',
+            'marketing site',
+            'marketing website',
+            'homepage',
+            'home page',
+            'launch page',
+            'waitlist page',
+            'coming soon page',
+            'pricing page',
+            'product page',
+            'sales page',
+            'splash page',
+            'microsite',
+            'portfolio site',
+            'portfolio website',
+        ],
+        weak: ['website', 'hero section', 'call to action', 'testimonials', 'waitlist', 'signup page'],
+    },
+    doc: {
+        // Bare "report" and "document" are often verbs ("sensors report telemetry"),
+        // so only a determiner or a qualifier makes them strong.
+        strong: [
+            'a report',
+            'the report',
+            'our report',
+            'this report',
+            'annual report',
+            'quarterly report',
+            'monthly report',
+            'weekly report',
+            'weekly reports',
+            'monthly reports',
+            'status report',
+            'progress report',
+            'research report',
+            'incident report',
+            'investor report',
+            'board report',
+            'impact report',
+            'one pager',
+            'one pagers',
+            'one page report',
+            'one page summary',
+            'write a report',
+            'write the report',
+            'write a one page',
+            'whitepaper',
+            'white paper',
+            'memo',
+            'memos',
+            'handbook',
+            'playbook',
+            'proposal',
+            'design doc',
+            'design document',
+            'a document',
+            'the document',
+            'write up',
+            'writeup',
+            'case study',
+            'postmortem',
+            'post mortem',
+            'rfc',
+        ],
+        weak: [
+            'report',
+            'reports',
+            'document',
+            'article',
+            'essay',
+            'summary',
+            'guide',
+            'manual',
+            'documentation',
+            'faq',
+            'readme',
+        ],
+    },
+};
+/** Nouns that name an app; before the first content cue, they keep the brief an app. */
+export const APP_CUES = [
+    'app',
+    'apps',
+    'application',
+    'applications',
+    'web app',
+    'mobile app',
+    'dashboard',
+    'dashboards',
+    'portal',
+    'platform',
+    'saas',
+    'software',
+    'system',
+    'tracker',
+    'crm',
+    'erp',
+    'admin panel',
+    'back office',
+    'internal tool',
+    'wiki',
+    'knowledge base',
+    'workspace',
+];
+/** A content cue followed by one of these names a tool that makes the content (an app). */
+const TOOL_NOUNS = [
+    'dashboard',
+    'dashboards',
+    'portal',
+    'app',
+    'apps',
+    'application',
+    'builder',
+    'builders',
+    'editor',
+    'editors',
+    'maker',
+    'makers',
+    'generator',
+    'generators',
+    'creator',
+    'creators',
+    'tool',
+    'tools',
+    'software',
+    'platform',
+    'manager',
+    'management',
+    'tracker',
+    'system',
+];
+/** Phrases where a cue word means something else; matches inside them are ignored. */
+const FALSE_FRIENDS = [
+    'deck of cards',
+    'card deck',
+    'card decks',
+    'boat deck',
+    'sun deck',
+    'deck chair',
+    'pool deck',
+    'presentation layer',
+];
+/** Every occurrence of every phrase as a word span, overlapping allowed. */
+function findSpans(words, phrases) {
+    const spans = [];
+    for (const phrase of phrases) {
+        const parts = phrase.split(' ');
+        for (let i = 0; i + parts.length <= words.length; i++) {
+            if (parts.every((part, j) => words[i + j] === part)) {
+                spans.push({ start: i, end: i + parts.length, phrase });
+            }
+        }
+    }
+    return spans;
+}
+const overlaps = (a, b) => a.start < b.end && b.start < a.end;
+function collectCues(words) {
+    const blocked = findSpans(words, FALSE_FRIENDS);
+    const candidates = [];
+    for (const kind of BLUEPRINT_KINDS) {
+        if (kind === 'app') {
+            for (const span of findSpans(words, APP_CUES)) {
+                candidates.push({ ...span, kind, strength: 'strong' });
+            }
+            continue;
+        }
+        for (const strength of ['strong', 'weak']) {
+            for (const span of findSpans(words, KIND_CUES[kind][strength])) {
+                candidates.push({ ...span, kind, strength });
+            }
+        }
+    }
+    // Longest phrase first (then earliest, then strongest), so "pitch deck" beats
+    // "pitch" and "deck", and each word belongs to at most one cue.
+    candidates.sort((a, b) => b.end - b.start - (a.end - a.start) ||
+        a.start - b.start ||
+        (a.strength === b.strength ? 0 : a.strength === 'strong' ? -1 : 1));
+    const accepted = [];
+    for (const candidate of candidates) {
+        if (blocked.some((span) => overlaps(span, candidate)))
+            continue;
+        if (accepted.some((span) => overlaps(span, candidate)))
+            continue;
+        accepted.push(candidate);
+    }
+    return accepted
+        .map((cue) => {
+        // "report generator", "slide deck builder": an app that makes the content.
+        const next = words[cue.end];
+        const tool = cue.kind !== 'app' && next !== undefined && TOOL_NOUNS.includes(next);
+        return tool
+            ? { kind: 'app', phrase: `${cue.phrase} ${next}`, strength: 'strong', index: cue.start }
+            : { kind: cue.kind, phrase: cue.phrase, strength: cue.strength, index: cue.start };
+    })
+        .sort((a, b) => a.index - b.index);
+}
+const quoted = (cues) => [...new Set(cues.map((cue) => `"${cue.phrase}"`))].join(', ');
+const CONTENT_ORDER = ['deck', 'page', 'doc'];
+/**
+ * Detects the kind a brief asks for. Deterministic: the same brief and options
+ * always give the same result. Throws a `RangeError` for an explicit kind this
+ * version does not know.
+ */
+export function detectBriefKind(brief, options = {}) {
+    const words = normalize(brief.slice(0, MAX_DETECTION_LENGTH)).split(' ').filter(Boolean);
+    const cues = collectCues(words);
+    if (options.kind !== undefined) {
+        if (!isBlueprintKind(options.kind))
+            throw new RangeError(unknownKindMessage(options.kind));
+        return {
+            kind: options.kind,
+            confidence: 'explicit',
+            ambiguous: false,
+            reason: `Kind "${options.kind}" was chosen explicitly.`,
+            cues,
+            suggestion: null,
+        };
+    }
+    const strongBy = (kind) => cues.filter((cue) => cue.kind === kind && cue.strength === 'strong');
+    const contentStrong = CONTENT_ORDER.filter((kind) => strongBy(kind).length > 0);
+    const appCues = strongBy('app');
+    if (contentStrong.length === 0) {
+        const weak = cues.filter((cue) => cue.kind !== 'app' && cue.strength === 'weak');
+        if (weak.length === 0) {
+            return {
+                kind: DEFAULT_BLUEPRINT_KIND,
+                confidence: 'fallback',
+                ambiguous: false,
+                reason: appCues.length > 0
+                    ? `App cues (${quoted(appCues)}) and no deck, page or doc cue: this is an app.`
+                    : 'No deck, page or doc cue: app is the default kind.',
+                cues,
+                suggestion: null,
+            };
+        }
+        // Weak cues only lean one way; the earliest weak cue breaks a tie.
+        const counts = CONTENT_ORDER.map((kind) => ({
+            kind,
+            count: weak.filter((cue) => cue.kind === kind).length,
+            first: weak.find((cue) => cue.kind === kind)?.index ?? Number.POSITIVE_INFINITY,
+        })).sort((a, b) => b.count - a.count || a.first - b.first);
+        const lean = counts[0].kind;
+        return {
+            kind: DEFAULT_BLUEPRINT_KIND,
+            confidence: 'fallback',
+            ambiguous: false,
+            reason: `Only weak ${lean} cues (${quoted(weak.filter((cue) => cue.kind === lean))}): kept app. Pass kind "${lean}" to make a ${lean}.`,
+            cues,
+            suggestion: lean,
+        };
+    }
+    if (contentStrong.length > 1) {
+        const listed = contentStrong.map((kind) => `${kind} (${quoted(strongBy(kind))})`).join(' and ');
+        const first = cues.find((cue) => cue.strength === 'strong' && contentStrong.includes(cue.kind));
+        return {
+            kind: DEFAULT_BLUEPRINT_KIND,
+            confidence: 'fallback',
+            ambiguous: true,
+            reason: `Cues for ${listed} conflict: kept app. Pass the kind you want explicitly.`,
+            cues,
+            suggestion: first?.kind ?? null,
+        };
+    }
+    const kind = contentStrong[0];
+    const kindCues = strongBy(kind);
+    const firstContent = kindCues[0].index;
+    const appBefore = appCues.filter((cue) => cue.index < firstContent);
+    if (appBefore.length > 0) {
+        return {
+            kind: DEFAULT_BLUEPRINT_KIND,
+            confidence: 'fallback',
+            ambiguous: true,
+            reason: `App cues (${quoted(appBefore)}) come before the ${kind} cues (${quoted(kindCues)}): kept app. Pass kind "${kind}" to make a ${kind}.`,
+            cues,
+            suggestion: kind,
+        };
+    }
+    return {
+        kind,
+        confidence: appCues.length > 0 ? 'medium' : 'high',
+        ambiguous: false,
+        reason: appCues.length > 0
+            ? `${capitalize(kind)} cues (${quoted(kindCues)}) lead the brief; app words (${quoted(appCues)}) only describe the subject.`
+            : `${capitalize(kind)} cues: ${quoted(kindCues)}.`,
+        cues,
+        suggestion: null,
+    };
+}
+function capitalize(text) {
+    return text.charAt(0).toUpperCase() + text.slice(1);
+}

package/dist/brief/limits.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Authoring bounds for briefs and generated outlines (all four kinds).
+ *
+ * The brief character cap matches historical app synthesis. Slide, section,
+ * block and text ceilings agree with the untrusted block contract
+ * (`@protoyard/blocks` BLOCK_CONTENT_LIMITS / BLOCK_LIMITS) so a synthesizer
+ * never emits drafts that the kind/block validators would reject for size.
+ *
+ * Oversized **briefs** are truncated with a stable notice (synthesis still
+ * runs). Oversized **outline structure** yields stable diagnostics; optional
+ * `truncate: true` clips deterministically instead of failing.
+ */
+import type { BlueprintKind } from '../kinds/kind.ts';
+/** Longer briefs are cut here; synthesizers read keywords, not essays. */
+export declare const MAX_BRIEF_LENGTH = 5000;
+/** Same cap for deck / page / doc content briefs. */
+export declare const MAX_CONTENT_BRIEF_LENGTH = 5000;
+/**
+ * Outline structure and text ceilings. Numbers mirror block content limits
+ * (markdown 4_000, short body 600, blocks-per-column 12) and keep generated
+ * decks/pages within a practical authoring range.
+ */
+export declare const OUTLINE_LIMITS: Readonly<{
+    /** Maximum slides in one generated or agent-authored deck outline. */
+    maxSlides: 64;
+    /** Maximum top-level sections in a page or doc outline. */
+    maxSections: 64;
+    /**
+     * Blocks nested under one slide or section (matches blocks-per-column
+     * capacity so a slide always fits).
+     */
+    maxBlocksPerUnit: 12;
+    /** Title / heading string length. */
+    maxTitleLength: 80;
+    /** Short body / bullet / card copy (block shortMarkdown). */
+    maxBodyLength: 600;
+    /** Long text / markdown block body (block markdown). */
+    maxTextLength: 4000;
+    /** Description / rationale line on the envelope. */
+    maxDescriptionLength: 280;
+}>;
+export type OutlineLimits = {
+    [Key in keyof typeof OUTLINE_LIMITS]: number;
+};
+export type BriefLimitCode = 'brief-too-long' | 'too-many-slides' | 'too-many-sections' | 'too-many-blocks' | 'title-too-long' | 'body-too-long' | 'text-too-long';
+export type BriefLimitIssue = {
+    code: BriefLimitCode;
+    path: (string | number)[];
+    message: string;
+    fix: string;
+    limit: number;
+    actual: number;
+};
+export type BoundBriefInput = {
+    /** Brief text ready for synthesis (never longer than the cap). */
+    brief: string;
+    /** True when the original was longer than the cap. */
+    truncated: boolean;
+    /** Original length before truncation. */
+    originalLength: number;
+    /** Documented notices for callers to surface (stable wording). */
+    notices: string[];
+};
+/** One slide or section unit inside a generated outline. */
+export type OutlineUnitInput = {
+    id?: string;
+    title?: string;
+    body?: string;
+    text?: string;
+    blocks?: unknown[];
+};
+/** Structure checked before synthesis or agent draft validation. */
+export type OutlineBoundsInput = {
+    kind: BlueprintKind;
+    title?: string;
+    description?: string;
+    slides?: OutlineUnitInput[];
+    sections?: OutlineUnitInput[];
+};
+export type CheckOutlineBoundsResult = {
+    ok: true;
+    issues: [];
+} | {
+    ok: false;
+    issues: BriefLimitIssue[];
+};
+export type ApplyOutlineBoundsResult = {
+    outline: OutlineBoundsInput;
+    truncated: boolean;
+    notices: string[];
+    issues: BriefLimitIssue[];
+};
+/**
+ * Enforce the brief character cap. Always returns a string ≤ the limit;
+ * never throws. Deterministic for the same input and limit.
+ */
+export declare function boundBriefInput(brief: string, options?: {
+    maxLength?: number;
+}): BoundBriefInput;
+/**
+ * Validate an outline structure against the documented ceilings.
+ * Does not mutate input. Empty collections are allowed (scaffolding).
+ */
+export declare function checkOutlineBounds(input: OutlineBoundsInput): CheckOutlineBoundsResult;
+/**
+ * Deterministically clip an outline to the ceilings. Prefer `checkOutlineBounds`
+ * when you want hard failures; use this when synthesis should continue with a
+ * documented truncation notice.
+ */
+export declare function applyOutlineBounds(input: OutlineBoundsInput): ApplyOutlineBoundsResult;
+/**
+ * Convenience for synthesizers: bound the brief, then return source + notices.
+ * Same behavior as historical `brief.slice(0, MAX_BRIEF_LENGTH)`.
+ */
+export declare function prepareBriefForSynthesis(brief: string, options?: {
+    maxLength?: number;
+}): BoundBriefInput;

package/dist/brief/limits.js

@@ -0,0 +1,217 @@
+/**
+ * Authoring bounds for briefs and generated outlines (all four kinds).
+ *
+ * The brief character cap matches historical app synthesis. Slide, section,
+ * block and text ceilings agree with the untrusted block contract
+ * (`@protoyard/blocks` BLOCK_CONTENT_LIMITS / BLOCK_LIMITS) so a synthesizer
+ * never emits drafts that the kind/block validators would reject for size.
+ *
+ * Oversized **briefs** are truncated with a stable notice (synthesis still
+ * runs). Oversized **outline structure** yields stable diagnostics; optional
+ * `truncate: true` clips deterministically instead of failing.
+ */
+/** Longer briefs are cut here; synthesizers read keywords, not essays. */
+export const MAX_BRIEF_LENGTH = 5_000;
+/** Same cap for deck / page / doc content briefs. */
+export const MAX_CONTENT_BRIEF_LENGTH = MAX_BRIEF_LENGTH;
+/**
+ * Outline structure and text ceilings. Numbers mirror block content limits
+ * (markdown 4_000, short body 600, blocks-per-column 12) and keep generated
+ * decks/pages within a practical authoring range.
+ */
+export const OUTLINE_LIMITS = Object.freeze({
+    /** Maximum slides in one generated or agent-authored deck outline. */
+    maxSlides: 64,
+    /** Maximum top-level sections in a page or doc outline. */
+    maxSections: 64,
+    /**
+     * Blocks nested under one slide or section (matches blocks-per-column
+     * capacity so a slide always fits).
+     */
+    maxBlocksPerUnit: 12,
+    /** Title / heading string length. */
+    maxTitleLength: 80,
+    /** Short body / bullet / card copy (block shortMarkdown). */
+    maxBodyLength: 600,
+    /** Long text / markdown block body (block markdown). */
+    maxTextLength: 4_000,
+    /** Description / rationale line on the envelope. */
+    maxDescriptionLength: 280,
+});
+function noticeBriefTruncated(original, limit) {
+    return `Brief truncated from ${original} to ${limit} characters (MAX_BRIEF_LENGTH).`;
+}
+/**
+ * Enforce the brief character cap. Always returns a string ≤ the limit;
+ * never throws. Deterministic for the same input and limit.
+ */
+export function boundBriefInput(brief, options = {}) {
+    const limit = options.maxLength ?? MAX_BRIEF_LENGTH;
+    const source = typeof brief === 'string' ? brief : '';
+    const originalLength = source.length;
+    if (originalLength <= limit) {
+        return { brief: source, truncated: false, originalLength, notices: [] };
+    }
+    return {
+        brief: source.slice(0, limit),
+        truncated: true,
+        originalLength,
+        notices: [noticeBriefTruncated(originalLength, limit)],
+    };
+}
+function issue(code, path, limit, actual, message, fix) {
+    return { code, path, message, fix, limit, actual };
+}
+function checkString(value, path, limit, code, label) {
+    if (value === undefined)
+        return null;
+    if (value.length <= limit)
+        return null;
+    return issue(code, path, limit, value.length, `${label} is ${value.length} characters; the limit is ${limit}.`, `Shorten ${label.toLowerCase()} to at most ${limit} characters.`);
+}
+function checkUnits(kind, units, collection, maxUnits) {
+    const issues = [];
+    if (!units)
+        return issues;
+    if (units.length > maxUnits) {
+        issues.push(issue(collection === 'slides' ? 'too-many-slides' : 'too-many-sections', [collection], maxUnits, units.length, `${kind} outline has ${units.length} ${collection}; the limit is ${maxUnits}.`, `Reduce ${collection} to at most ${maxUnits}.`));
+    }
+    const limit = OUTLINE_LIMITS.maxBlocksPerUnit;
+    units.forEach((unit, index) => {
+        const pathBase = [collection, index];
+        const titleIssue = checkString(unit.title, [...pathBase, 'title'], OUTLINE_LIMITS.maxTitleLength, 'title-too-long', 'Title');
+        if (titleIssue)
+            issues.push(titleIssue);
+        const bodyIssue = checkString(unit.body, [...pathBase, 'body'], OUTLINE_LIMITS.maxBodyLength, 'body-too-long', 'Body');
+        if (bodyIssue)
+            issues.push(bodyIssue);
+        const textIssue = checkString(unit.text, [...pathBase, 'text'], OUTLINE_LIMITS.maxTextLength, 'text-too-long', 'Text');
+        if (textIssue)
+            issues.push(textIssue);
+        const blockCount = Array.isArray(unit.blocks) ? unit.blocks.length : 0;
+        if (blockCount > limit) {
+            issues.push(issue('too-many-blocks', [...pathBase, 'blocks'], limit, blockCount, `${collection.slice(0, -1)} has ${blockCount} blocks; the limit is ${limit}.`, `Keep at most ${limit} blocks per ${collection.slice(0, -1)}.`));
+        }
+    });
+    return issues;
+}
+/**
+ * Validate an outline structure against the documented ceilings.
+ * Does not mutate input. Empty collections are allowed (scaffolding).
+ */
+export function checkOutlineBounds(input) {
+    const issues = [];
+    const titleIssue = checkString(input.title, ['title'], OUTLINE_LIMITS.maxTitleLength, 'title-too-long', 'Title');
+    if (titleIssue)
+        issues.push(titleIssue);
+    const descriptionIssue = checkString(input.description, ['description'], OUTLINE_LIMITS.maxDescriptionLength, 'body-too-long', 'Description');
+    if (descriptionIssue)
+        issues.push(descriptionIssue);
+    if (input.kind === 'deck') {
+        issues.push(...checkUnits('deck', input.slides, 'slides', OUTLINE_LIMITS.maxSlides));
+        if (input.sections && input.sections.length > 0) {
+            issues.push(issue('too-many-sections', ['sections'], 0, input.sections.length, 'Deck outlines use slides, not sections.', 'Move content into slides and omit sections.'));
+        }
+    }
+    else if (input.kind === 'page' || input.kind === 'doc') {
+        issues.push(...checkUnits(input.kind, input.sections, 'sections', OUTLINE_LIMITS.maxSections));
+        if (input.slides && input.slides.length > 0) {
+            issues.push(issue('too-many-slides', ['slides'], 0, input.slides.length, `${input.kind} outlines use sections, not slides.`, 'Move content into sections and omit slides.'));
+        }
+    }
+    else {
+        // app: no slide/section outline; only envelope strings if present
+        if (input.slides && input.slides.length > 0) {
+            issues.push(issue('too-many-slides', ['slides'], 0, input.slides.length, 'App briefs do not take a slide outline.', 'Omit slides for kind app.'));
+        }
+        if (input.sections && input.sections.length > 0) {
+            issues.push(issue('too-many-sections', ['sections'], 0, input.sections.length, 'App briefs do not take a section outline.', 'Omit sections for kind app.'));
+        }
+    }
+    return issues.length === 0 ? { ok: true, issues: [] } : { ok: false, issues };
+}
+function clipString(value, limit) {
+    if (value === undefined)
+        return undefined;
+    return value.length <= limit ? value : value.slice(0, limit);
+}
+function clipUnits(units, maxUnits) {
+    if (!units)
+        return { units: undefined, clippedUnits: 0, clippedFields: 0 };
+    let clippedFields = 0;
+    const sliced = units.slice(0, maxUnits);
+    const clippedUnits = units.length - sliced.length;
+    const next = sliced.map((unit) => {
+        const title = clipString(unit.title, OUTLINE_LIMITS.maxTitleLength);
+        const body = clipString(unit.body, OUTLINE_LIMITS.maxBodyLength);
+        const text = clipString(unit.text, OUTLINE_LIMITS.maxTextLength);
+        if (title !== unit.title || body !== unit.body || text !== unit.text)
+            clippedFields += 1;
+        const blocks = Array.isArray(unit.blocks)
+            ? unit.blocks.slice(0, OUTLINE_LIMITS.maxBlocksPerUnit)
+            : unit.blocks;
+        if (Array.isArray(unit.blocks) && unit.blocks.length > OUTLINE_LIMITS.maxBlocksPerUnit) {
+            clippedFields += 1;
+        }
+        return { ...unit, title, body, text, blocks };
+    });
+    return { units: next, clippedUnits, clippedFields };
+}
+/**
+ * Deterministically clip an outline to the ceilings. Prefer `checkOutlineBounds`
+ * when you want hard failures; use this when synthesis should continue with a
+ * documented truncation notice.
+ */
+export function applyOutlineBounds(input) {
+    const notices = [];
+    let truncated = false;
+    const outline = {
+        kind: input.kind,
+        title: clipString(input.title, OUTLINE_LIMITS.maxTitleLength),
+        description: clipString(input.description, OUTLINE_LIMITS.maxDescriptionLength),
+    };
+    if (outline.title !== input.title || outline.description !== input.description) {
+        truncated = true;
+        notices.push('Envelope title/description clipped to outline text limits.');
+    }
+    if (input.kind === 'deck') {
+        const { units, clippedUnits, clippedFields } = clipUnits(input.slides, OUTLINE_LIMITS.maxSlides);
+        outline.slides = units;
+        if (clippedUnits > 0) {
+            truncated = true;
+            notices.push(`Slides truncated from ${(input.slides?.length ?? 0).toString()} to ${OUTLINE_LIMITS.maxSlides}.`);
+        }
+        if (clippedFields > 0) {
+            truncated = true;
+            notices.push('Slide titles, bodies or blocks clipped to outline limits.');
+        }
+    }
+    else if (input.kind === 'page' || input.kind === 'doc') {
+        const { units, clippedUnits, clippedFields } = clipUnits(input.sections, OUTLINE_LIMITS.maxSections);
+        outline.sections = units;
+        if (clippedUnits > 0) {
+            truncated = true;
+            notices.push(`Sections truncated from ${(input.sections?.length ?? 0).toString()} to ${OUTLINE_LIMITS.maxSections}.`);
+        }
+        if (clippedFields > 0) {
+            truncated = true;
+            notices.push('Section titles, bodies or blocks clipped to outline limits.');
+        }
+    }
+    // Re-check so callers always get a full issue list for anything still wrong
+    // (e.g. deck with leftover sections field).
+    const checked = checkOutlineBounds(outline);
+    return {
+        outline,
+        truncated,
+        notices,
+        issues: checked.ok ? [] : checked.issues,
+    };
+}
+/**
+ * Convenience for synthesizers: bound the brief, then return source + notices.
+ * Same behavior as historical `brief.slice(0, MAX_BRIEF_LENGTH)`.
+ */
+export function prepareBriefForSynthesis(brief, options = {}) {
+    return boundBriefInput(brief, options);
+}