Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
import {
resolveProducer,
} from "@hypit/kernel";
import type {
Candidate,
Satisfaction,
CandidateRoot,
CompiledGraph,
GraphValueRef,
LinkedProgram,
LogicalOutput,
OperationNode,
ProducerRef,
TypeRef,
} from "@hypit/protocol";
export type FragmentInputRef = {
readonly kind: "fragment-input";
readonly name: string;
};
export type FragmentOperationRef = {
readonly kind: "fragment-operation";
readonly operation: string;
};
export type FragmentValueRef = FragmentInputRef | FragmentOperationRef;
export type FragmentOperationResult =
| { readonly kind: "output"; readonly name: string }
| { readonly kind: "need"; readonly name: string };
export type FragmentOperation = {
readonly id: string;
readonly producer: ProducerRef;
readonly inputs: Readonly<Record<string, FragmentValueRef>>;
readonly result: FragmentOperationResult;
};
export type FragmentExport = {
readonly name: string;
readonly type: TypeRef;
readonly root: FragmentOperationRef;
};
export type GraphFragment = {
readonly format: "hypit.fragment@1";
readonly id: string;
readonly inputs: readonly { readonly name: string; readonly type: TypeRef }[];
readonly operations: readonly FragmentOperation[];
readonly exports: readonly FragmentExport[];
};
export type FragmentInstanceRequest = {
/** Stable author instance identity, not a content-deduplication key. */
readonly id: string;
readonly fragment: string;
readonly inputs: Readonly<Record<string, GraphValueRef>>;
};
export type ElaboratedFragmentExport = {
readonly name: string;
readonly type: TypeRef;
readonly root: CandidateRoot;
};
export type ElaboratedFragment = {
readonly format: "hypit.fragment-instance@1";
readonly id: string;
readonly fragment: string;
readonly instance: string;
readonly inputs: Readonly<Record<string, GraphValueRef>>;
readonly operations: readonly OperationNode[];
readonly exports: readonly ElaboratedFragmentExport[];
};
export type FragmentContribution = {
readonly outputs: readonly LogicalOutput[];
readonly candidates: readonly Candidate[];
readonly operations: readonly OperationNode[];
/** Explicit Run-Graph satisfactions; Author contributions leave this absent. */
readonly satisfactions?: readonly Satisfaction[];
};
export type RunFragmentExport = {
readonly name: string;
readonly candidate: string;
readonly type: TypeRef;
};
export type RunFragmentContribution = FragmentContribution & {
readonly exports: readonly RunFragmentExport[];
};
export class FragmentError extends Error {
readonly code: string;
readonly subject: string | undefined;
constructor(code: string, message: string, subject?: string) {
super(message);
this.name = "FragmentError";
this.code = code;
this.subject = subject;
}
}
function assert(condition: unknown, code: string, message: string, subject?: string): asserts condition {
if (!condition) throw new FragmentError(code, message, subject);
}
function sameType(left: TypeRef, right: TypeRef): boolean {
return left.module.name === right.module.name
&& left.module.version === right.module.version
&& left.name === right.name;
}
function typeName(type: TypeRef): string {
return `${type.module.name}@${type.module.version}#${type.name}`;
}
function exactKeys(
actual: Readonly<Record<string, unknown>>,
expected: readonly string[],
subject: string,
): void {
const left = Object.keys(actual).sort();
const right = [...expected].sort();
assert(
JSON.stringify(left) === JSON.stringify(right),
"FRAGMENT_PORT_BINDING_MISMATCH",
`${subject} binds [${left.join(", ")}] but declares [${right.join(", ")}]`,
subject,
);
}
function normalizeFragmentRef(ref: FragmentValueRef): FragmentValueRef {
if (ref.kind === "fragment-input") return { kind: "fragment-input", name: ref.name };
assert(
ref.kind === "fragment-operation",
"INVALID_FRAGMENT_REFERENCE",
"Fragment references must name a declared input or local Operation",
);
return { kind: "fragment-operation", operation: ref.operation };
}
function normalizeOperation(operation: FragmentOperation): FragmentOperation {
return {
id: operation.id,
producer: operation.producer,
inputs: Object.fromEntries(
Object.entries(operation.inputs)
.sort(([left], [right]) => left.localeCompare(right))
.map(([name, ref]) => [name, normalizeFragmentRef(ref)]),
),
result: operation.result.kind === "output"
? { kind: "output", name: operation.result.name }
: {
kind: "need",
name: operation.result.name,
},
};
}
function normalizeExport(item: FragmentExport): FragmentExport {
return {
name: item.name,
type: item.type,
root: normalizeFragmentRef(item.root) as FragmentOperationRef,
};
}
function fragmentContent(fragment: Omit<GraphFragment, "id">): Omit<GraphFragment, "id"> {
return {
format: "hypit.fragment@1",
inputs: [...fragment.inputs]
.map((input) => ({ name: input.name, type: input.type }))
.sort((left, right) => left.name.localeCompare(right.name)),
operations: [...fragment.operations].map(normalizeOperation).sort((left, right) => left.id.localeCompare(right.id)),
exports: [...fragment.exports].map(normalizeExport).sort((left, right) => left.name.localeCompare(right.name)),
};
}
export function sealGraphFragment(
fragment: Omit<GraphFragment, "format" | "id">,
): GraphFragment {
const content = fragmentContent({ format: "hypit.fragment@1", ...fragment });
const producers = content.operations.map((operation) =>
`${operation.producer.module.name}@${operation.producer.module.version}#${operation.producer.name}:${operation.id}`);
const exports = content.exports.map((item) => item.name);
return { ...content, id: `fragment:${producers.join("+")}=>${exports.join("+")}` };
}
function resultType(program: LinkedProgram, operation: FragmentOperation): TypeRef {
const producer = resolveProducer(program.closure, operation.producer);
if (operation.result.kind === "output") {
const output = producer.outputs.find((port) => port.name === operation.result.name);
assert(
output !== undefined && producer.needs.length === 0,
"FRAGMENT_RESULT_MISMATCH",
`${operation.id} does not produce output ${operation.result.name}`,
operation.id,
);
return output.type;
}
const need = producer.needs.find((port) => port.name === operation.result.name);
assert(
need !== undefined && producer.outputs.length === 0,
"FRAGMENT_RESULT_MISMATCH",
`${operation.id} does not request Need ${operation.result.name}`,
operation.id,
);
return need.returns;
}
export function verifyGraphFragment(program: LinkedProgram, fragment: GraphFragment): void {
assert(fragment.format === "hypit.fragment@1", "UNSUPPORTED_FRAGMENT", "unsupported Graph Fragment format");
assert(fragment.id.trim().length > 0, "INVALID_FRAGMENT_ID", "Graph Fragment id is empty");
assert(fragment.exports.length > 0, "EMPTY_FRAGMENT_EXPORTS", `${fragment.id} has no exports`);
const inputs = new Map<string, TypeRef>();
for (const input of fragment.inputs) {
assert(input.name.length > 0, "EMPTY_FRAGMENT_INPUT", `${fragment.id} has an empty input name`);
assert(!inputs.has(input.name), "DUPLICATE_FRAGMENT_INPUT", `${fragment.id} repeats input ${input.name}`);
inputs.set(input.name, input.type);
}
const operations = new Map<string, FragmentOperation>();
for (const operation of fragment.operations) {
assert(operation.id.length > 0, "EMPTY_FRAGMENT_OPERATION", `${fragment.id} has an empty Operation id`);
assert(!operations.has(operation.id), "DUPLICATE_FRAGMENT_OPERATION", `${fragment.id} repeats ${operation.id}`);
operations.set(operation.id, operation);
const producer = resolveProducer(program.closure, operation.producer);
exactKeys(operation.inputs, producer.inputs.map((port) => port.name), `${fragment.id}.${operation.id}`);
}
const visiting = new Set<string>();
const visited = new Set<string>();
const operationType = (id: string): TypeRef => {
const operation = operations.get(id);
assert(operation !== undefined, "UNKNOWN_FRAGMENT_OPERATION", `${fragment.id} references ${id}`, id);
if (visited.has(id)) return resultType(program, operation);
assert(!visiting.has(id), "FRAGMENT_CYCLE", `${fragment.id} cycles through ${id}`, id);
visiting.add(id);
const producer = resolveProducer(program.closure, operation.producer);
for (const port of producer.inputs) {
const ref = operation.inputs[port.name];
assert(ref !== undefined, "FRAGMENT_PORT_BINDING_MISMATCH", `${operation.id}.${port.name} is unbound`);
const supplied = ref.kind === "fragment-input"
? inputs.get(ref.name)
: operationType(ref.operation);
assert(supplied !== undefined, "UNKNOWN_FRAGMENT_INPUT", `${fragment.id} references input ${ref.kind === "fragment-input" ? ref.name : ref.operation}`);
assert(
sameType(supplied, port.type),
"FRAGMENT_INPUT_TYPE_MISMATCH",
`${operation.id}.${port.name} wants ${typeName(port.type)} but receives ${typeName(supplied)}`,
operation.id,
);
}
visiting.delete(id);
visited.add(id);
return resultType(program, operation);
};
const exports = new Set<string>();
const reachableOperations = new Set<string>();
const collectDependencies = (ref: FragmentValueRef): void => {
if (ref.kind === "fragment-input" || reachableOperations.has(ref.operation)) return;
reachableOperations.add(ref.operation);
const operation = operations.get(ref.operation);
assert(operation !== undefined, "UNKNOWN_FRAGMENT_OPERATION", `${fragment.id} references ${ref.operation}`);
Object.values(operation.inputs).forEach(collectDependencies);
};
for (const item of fragment.exports) {
assert(item.name.length > 0, "EMPTY_FRAGMENT_EXPORT", `${fragment.id} has an empty export name`);
assert(!exports.has(item.name), "DUPLICATE_FRAGMENT_EXPORT", `${fragment.id} repeats export ${item.name}`);
exports.add(item.name);
assert(
item.root.kind === "fragment-operation",
"INVALID_FRAGMENT_EXPORT_ROOT",
`${fragment.id}.${item.name} must export a local Operation result`,
);
const supplied = operationType(item.root.operation);
assert(
sameType(supplied, item.type),
"FRAGMENT_EXPORT_TYPE_MISMATCH",
`${fragment.id}.${item.name} declares ${typeName(item.type)} but returns ${typeName(supplied)}`,
);
collectDependencies(item.root);
}
for (const id of operations.keys()) {
assert(
reachableOperations.has(id),
"UNREACHABLE_FRAGMENT_OPERATION",
`${fragment.id}.${id} contributes to no export`,
id,
);
}
}
function normalizeGraphRef(ref: GraphValueRef): GraphValueRef {
if (ref.kind === "record") return { kind: "record", id: ref.id };
if (ref.kind === "logical-output") return { kind: "logical-output", id: ref.id };
assert(
ref.kind === "operation-result",
"INVALID_FRAGMENT_BINDING",
"Fragment inputs must bind to a Graph Value reference",
);
return { kind: "operation-result", operation: ref.operation };
}
function hygienicId(kind: string, instance: string, local: string): string {
return `${kind}:${encodeURIComponent(instance)}:${encodeURIComponent(local)}`;
}
export function elaborateGraphFragment(
program: LinkedProgram,
fragment: GraphFragment,
request: FragmentInstanceRequest,
): ElaboratedFragment {
verifyGraphFragment(program, fragment);
assert(request.id.length > 0, "EMPTY_FRAGMENT_INSTANCE", "Fragment instance id is empty");
assert(request.fragment === fragment.id, "FRAGMENT_INSTANCE_MISMATCH", `${request.id} locks another Fragment`);
exactKeys(request.inputs, fragment.inputs.map((input) => input.name), request.id);
const inputs = Object.fromEntries(
Object.entries(request.inputs)
.sort(([left], [right]) => left.localeCompare(right))
.map(([name, ref]) => [name, normalizeGraphRef(ref)]),
);
const operationIds = new Map(fragment.operations.map((operation) => [
operation.id,
hygienicId("operation", request.id, operation.id),
]));
const mapRef = (ref: FragmentValueRef): GraphValueRef => {
if (ref.kind === "fragment-input") {
const bound = inputs[ref.name];
assert(bound !== undefined, "UNKNOWN_FRAGMENT_INPUT", `${request.id} does not bind ${ref.name}`);
return bound;
}
const operation = operationIds.get(ref.operation);
assert(operation !== undefined, "UNKNOWN_FRAGMENT_OPERATION", `${fragment.id} references ${ref.operation}`);
return { kind: "operation-result", operation };
};
const operations: OperationNode[] = fragment.operations.map((operation) => {
const id = operationIds.get(operation.id) as string;
const record = hygienicId("record", request.id, operation.id);
return {
id,
producer: operation.producer,
inputs: Object.fromEntries(Object.entries(operation.inputs).map(([name, ref]) => [name, mapRef(ref)])),
result: operation.result.kind === "output"
? { kind: "output", name: operation.result.name, record }
: {
kind: "need",
name: operation.result.name,
id: hygienicId("need", request.id, operation.id),
record,
},
};
});
const exports: ElaboratedFragmentExport[] = fragment.exports.map((item) => {
const root = mapRef(item.root);
assert(root.kind === "operation-result", "INVALID_FRAGMENT_EXPORT_ROOT", item.name);
return {
name: item.name,
type: item.type,
root: { kind: "operation" as const, result: root },
};
});
const content = {
format: "hypit.fragment-instance@1" as const,
fragment: fragment.id,
instance: request.id,
inputs,
operations,
exports,
};
return { ...content, id: `fragment-instance:${request.id}` };
}
function exportMap(instance: ElaboratedFragment): Map<string, ElaboratedFragmentExport> {
return new Map(instance.exports.map((item) => [item.name, item]));
}
function reachableOperationIds(
instance: ElaboratedFragment,
selected: readonly ElaboratedFragmentExport[],
): Set<string> {
const operations = new Map(instance.operations.map((operation) => [operation.id, operation]));
const reachable = new Set<string>();
const visit = (id: string): void => {
if (reachable.has(id)) return;
reachable.add(id);
const operation = operations.get(id);
assert(operation !== undefined, "UNKNOWN_ELABORATED_OPERATION", `${instance.instance} references ${id}`);
for (const ref of Object.values(operation.inputs)) {
if (ref.kind === "operation-result") visit(ref.operation);
}
};
for (const item of selected) {
assert(item.root.kind === "operation", "INVALID_FRAGMENT_EXPORT_ROOT", item.name);
visit(item.root.result.operation);
}
return reachable;
}
function bindExports(
instance: ElaboratedFragment,
bindings: Readonly<Record<string, string>>,
requireAll: boolean,
): FragmentContribution {
const available = exportMap(instance);
if (requireAll) exactKeys(bindings, instance.exports.map((item) => item.name), instance.instance);
assert(Object.keys(bindings).length > 0, "EMPTY_FRAGMENT_BINDING", `${instance.instance} binds no exports`);
const selected = Object.keys(bindings).map((name) => {
const item = available.get(name);
assert(item !== undefined, "UNKNOWN_FRAGMENT_EXPORT", `${instance.instance} has no export ${name}`);
return item;
});
const candidates: Candidate[] = selected.map((item) => {
const output = bindings[item.name] as string;
assert(output.length > 0, "EMPTY_LOGICAL_OUTPUT_ID", `${instance.instance}.${item.name} output is empty`);
return {
id: hygienicId("candidate", instance.instance, item.name),
type: item.type,
root: item.root,
};
});
const outputs: LogicalOutput[] = requireAll
? selected.map((item, index) => ({
id: bindings[item.name] as string,
type: item.type,
primary: candidates[index]!.id,
}))
: [];
const reachable = reachableOperationIds(instance, selected);
return {
outputs,
candidates,
operations: instance.operations.filter((operation) => reachable.has(operation.id)),
...(requireAll
? {}
: {
satisfactions: selected.map((item, index) => ({
output: bindings[item.name] as string,
candidate: candidates[index]!.id,
})),
}),
};
}
/**
* Instantiate a Run-Graph Fragment without deciding which Author Logical Outputs it will satisfy.
* Multiple exports share the instance's internal Operations; separate calls always create separate
* instances because identity comes from the already elaborated `instance.instance` path.
*/
export function exportRunFragment(
instance: ElaboratedFragment,
names: readonly string[] = instance.exports.map((item) => item.name),
): RunFragmentContribution {
assert(names.length > 0, "EMPTY_FRAGMENT_BINDING", `${instance.instance} exports no Run values`);
assert(new Set(names).size === names.length, "DUPLICATE_FRAGMENT_EXPORT", `${instance.instance} repeats a Run export`);
const available = exportMap(instance);
const selected = names.map((name) => {
const item = available.get(name);
assert(item !== undefined, "UNKNOWN_FRAGMENT_EXPORT", `${instance.instance} has no export ${name}`);
return item;
});
const candidates: Candidate[] = selected.map((item) => ({
id: hygienicId("candidate", instance.instance, item.name),
type: item.type,
root: item.root,
}));
const reachable = reachableOperationIds(instance, selected);
return {
outputs: [],
candidates,
operations: instance.operations.filter((operation) => reachable.has(operation.id)),
exports: selected.map((item, index) => ({
name: item.name,
candidate: candidates[index]!.id,
type: item.type,
})),
};
}
/** Bind all Fragment exports as new author-visible Logical Outputs. */
export function bindAuthorFragment(
instance: ElaboratedFragment,
outputs: Readonly<Record<string, string>>,
): FragmentContribution {
return bindExports(instance, outputs, true);
}
/** Merge already elaborated contributions; final Graph validation remains Core's authority. */
export function mergeFragmentContributions(
graph: Pick<CompiledGraph, "outputs" | "candidates" | "operations">,
...contributions: readonly FragmentContribution[]
): Pick<CompiledGraph, "outputs" | "candidates" | "operations"> {
return {
outputs: [...graph.outputs, ...contributions.flatMap((item) => item.outputs)],
candidates: [...graph.candidates, ...contributions.flatMap((item) => item.candidates)],
operations: [...graph.operations, ...contributions.flatMap((item) => item.operations)],
};
}