import { GoalError } from "./goal.ts";
import type { compatibilitySlice } from "./stdlib.ts";
type JavaScriptReadmeSections = {
/** Title, runtime and public API instructions. */
introduction: string;
/** Project-specific instructions about dependencies, network access and build requirements. */
packagePolicy: string;
scope: string;
exclusions: string;
};
/** Append the goal schema and inherited context to the project's builder instructions. */
export function compatibilityReadme(
bundle: ReturnType<typeof compatibilitySlice>,
contract: string,
): string {
return renderReadme(bundle, contract, false);
}
function renderReadme(
{ goals, submission }: ReturnType<typeof compatibilitySlice>,
contract: string,
historicalWording: boolean,
): string {
const implementation = goals.find(goal => goal.id === submission.contextParent);
const charter = goals.find(goal => goal.id === implementation?.context?.parent);
const adjustment = implementation?.context?.adjustments?.[0];
const focus = goals.find(goal => goal.id === adjustment?.priorities[0]?.goal);
const grant = charter?.context?.grants?.find(grant => grant.id === adjustment?.using.id);
const obligations = charter?.context?.obligations;
const review = charter?.nextReview;
if (!implementation || !charter || !focus || !grant || !obligations || !review) {
throw new GoalError("A compatibility README needs a complete compatibility slice");
}
const reviewText = "on" in review ? `follows ${review.on}`
: "at" in review ? `is due at ${review.at}` : `follows evidence from ${review.evidence}`;
const project = charter.id.slice(0, -".context.charter".length);
const idDescription = obligations.every(id => id.startsWith(`${project}-`)) ? "project-prefixed id" : "id";
const schema = historicalWording
? `Each has a stable ${idDescription}, plain statement and acceptance object mapping stable kebab-case entry IDs to required observable behavior.`
: `Each behavioral goal has a stable ${idDescription}, plain statement and acceptance object mapping stable entry IDs to required observable behavior.`;
const product = historicalWording ? "library" : "product";
const original = historicalWording ? "original " : "";
const protectedGoals = historicalWording
? `all ${obligations.length} existing behavioral goals as protected obligations. Their original IDs, statements, acceptance entries, holds and review settings are unchanged.`
: `${obligations.length} behavioral goals as protected obligations.`;
return `${contract.trimEnd()}
## Goal schema
The JSON root is an array of mnmx goal specifications. ${schema} owner, nextReview, hold and measure are engine metadata: owner is ${charter.owner}; review ${reviewText}; hold.max=0; measure.demonstrated=true. A host may hydrate each specification through goal(spec); the reconstructed ${product} need not depend on mnmx. Implement every acceptance entry; the metadata does not prescribe internal implementation.
## Inherited goal context (version ${submission.version})
The charter \`${charter.id}\` adopts ${protectedGoals} Every registered acceptance entry remains required. These mechanical obligations cannot be weakened by local priorities or bypassed with break-glass overrides.
The ordered charter priorities are compatibility, then implementation clarity. Its explicit \`${grant.id}\` grant lets the direct child \`${implementation.id}\` tailor that priority group within its own scope. That child substitutes \`${focus.id}\`, which explicitly serves compatibility, and retains clarity second. The grant does not allow further delegation. Owners are trusted harness declarations, not cryptographic authorization.
Project focus: ${focus.statement}
\`context.parent\` is the single accountable context parent; \`serves\` links contribution, not policy inheritance. \`context.obligations\` protects measured policy goals throughout the context subtree. \`groups\` are ordered guidance; \`grants\` and \`adjustments\` carry the authority and rationale for local changes. Guidance goals have no acceptance claims. \`submission.json\` explicitly identifies them and tells the harness to place its aggregate submission under the implementation context. It still measures every ${original}behavioral goal.
These are reconstruction harness definitions, not requirements to add mnmx or organizational APIs to the reconstructed product. Lifecycle remains explicitly declared; no artificial dependency ordering is added to independent behavioral requirements. Priorities guide work and tradeoffs within the stated scope; they never waive a required behavior. Report unresolved ambiguity in BUILDER-REPORT.md.
`;
}
/** Render the testbed's historical JavaScript library reconstruction template. */
export function javascriptCompatibilityReadme(
bundle: ReturnType<typeof compatibilitySlice>,
{ introduction, packagePolicy, scope, exclusions }: JavaScriptReadmeSections,
): string {
return renderReadme(bundle, `${introduction.trim()}
The builder receives this README and goals.json only. No source, tests or prior implementation is input. Any implementation is acceptable if it satisfies the public behavior. ${packagePolicy.trim()}
## Scope
${scope.trim()}
Excluded: ${exclusions.trim()}
All acceptance entries in goals.json are required observable contracts, including examples and edge semantics. The cases are complementary examples of the scoped API, not permission to special-case the examples. Unless an entry says otherwise, object and array results use ordinary JavaScript values, functions are synchronous, text is Unicode, iteration uses JavaScript property order, and invalid inputs outside the explicitly required cases are unspecified. No byte size, benchmark speed, old-engine compatibility or source similarity requirement applies.`, true);
}