@hraness/slopcamera 3.2.4

package/apps/desktop/code/file-candidate.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+
+import {
+  RepositoryRelativePathSchema,
+  Sha256Schema,
+} from "../contracts";
+
+export const WORKFLOW_FILE_CANDIDATE_VERSION =
+  "slopcamera-workflow-file-candidate-v1" as const;
+
+const CandidatePathSchema = RepositoryRelativePathSchema.and(
+  z.string().max(256),
+);
+
+export const WorkflowFileCandidateSchema = z.strictObject({
+  bytes: z.number().int().safe().positive().optional(),
+  kind: z.literal("file"),
+  mediaType: z.string()
+    .max(160)
+    .regex(
+      /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/u,
+    )
+    .optional(),
+  path: CandidatePathSchema,
+  sha256: Sha256Schema.optional(),
+  version: z.literal(WORKFLOW_FILE_CANDIDATE_VERSION),
+}).superRefine((candidate, context) => {
+  if ((candidate.bytes === undefined) !== (candidate.sha256 === undefined)) {
+    context.addIssue({
+      code: "custom",
+      message: "Exact file candidates require both bytes and sha256.",
+    });
+  }
+});
+
+export type WorkflowFileCandidate =
+  z.infer<typeof WorkflowFileCandidateSchema>;
+
+interface FileCandidateBase {
+  readonly mediaType?: string;
+  readonly path: string;
+}
+
+export type FileCandidateInput =
+  | string
+  | (FileCandidateBase & {
+      readonly bytes?: never;
+      readonly sha256?: never;
+    })
+  | (FileCandidateBase & {
+      readonly bytes: number;
+      readonly sha256: string;
+    });
+
+/**
+ * Declares local-file authority in workflow input without opening the file.
+ *
+ * Trusted compute may choose among these inert declarations. A registered
+ * media/Gateway operation still reopens, hashes, and binds the chosen file in
+ * its exact node plan before effect authorization.
+ */
+export function fileCandidate(input: FileCandidateInput): WorkflowFileCandidate {
+  const candidate = typeof input === "string" ? { path: input } : input;
+  return WorkflowFileCandidateSchema.parse({
+    ...candidate,
+    kind: "file",
+    version: WORKFLOW_FILE_CANDIDATE_VERSION,
+  });
+}

package/apps/desktop/code/graph-builder.ts

@@ -0,0 +1,10 @@
+/** Desktop compatibility façade for the canonical SDK graph builder. */
+export {
+  WorkflowGraphBuilder,
+  defineWorkflowFragment,
+  operationContract,
+  type OperationDiscoveryProvider as OperationDiscoverySource,
+  type OperationNodeOptions,
+  type UntypedOperationRequest,
+  type WorkflowFragment,
+} from "@hraness/slopcamera/code/advanced";

package/apps/desktop/code/host-resource-policy.ts

@@ -0,0 +1,55 @@
+import type {
+  HostResourceClaim,
+  HostResourceCoordinator,
+} from "@hraness/slopcamera/host-resources";
+
+import type {
+  OperationResourceClaim,
+  OperationResourceKind,
+} from "../application/operation";
+
+const PHYSICAL_HOST_RESOURCE_BY_OPERATION: Readonly<Partial<Record<
+  OperationResourceKind,
+  HostResourceClaim["resource"]
+>>> = Object.freeze({
+  browser: "browser",
+  "capture-device": "capture-device",
+  cpu: "cpu",
+  ffmpeg: "ffmpeg",
+  "local-io": "local-io",
+  network: "network",
+  "paid-call": "paid-call",
+  "project-render": "video-encode",
+  vision: "vision",
+  whisper: "whisper",
+});
+
+/**
+ * Convert semantic operation claims into the machine-wide physical budget.
+ * Every FFmpeg recipe remains conservatively single-flight until its complete
+ * decoder, filter, and encoder thread budget is bound into the exact plan.
+ */
+export function physicalHostResourceClaims(
+  resources: readonly OperationResourceClaim[],
+  coordinator: HostResourceCoordinator,
+): readonly HostResourceClaim[] {
+  const totals = new Map<string, number>();
+  for (const claim of resources) {
+    const resource = PHYSICAL_HOST_RESOURCE_BY_OPERATION[claim.resource];
+    if (resource === undefined) continue;
+    totals.set(resource, (totals.get(resource) ?? 0) + claim.amount);
+  }
+  if (resources.some(claim => (
+    claim.resource === "ffmpeg" || claim.resource === "project-render"
+  ))) {
+    for (const resource of ["cpu", "ffmpeg"] as const) {
+      const capacity = coordinator.profile.capacities.find(
+        candidate => candidate.resource === resource,
+      );
+      if (capacity !== undefined) totals.set(resource, capacity.limit);
+    }
+  }
+  return [...totals]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([resource, amount]) => ({ amount, resource }));
+}

package/apps/desktop/code/plan-contracts.ts

@@ -0,0 +1,159 @@
+import { z } from "zod";
+import {
+  AuthoredWorkflowGraphV1Schema,
+  GRAPH_ABI,
+  LEGACY_GRAPH_ABI,
+  GraphCompilerLimitsSchema,
+  JsonValueSchema,
+  MAX_SERIALIZED_GRAPH_NODES,
+  NodeKeySchema,
+  NonnegativeSafeIntegerSchema,
+  OperationDiscoverySchema as PortableOperationDiscoverySchema,
+  RequirementEnvelopeSchema,
+  Sha256Schema,
+} from "@hraness/slopcamera/code/advanced";
+
+import { OPERATION_KINDS } from "../application/operation";
+
+export const OperationKindSchema = z.enum(OPERATION_KINDS);
+
+/**
+ * The portable graph accepts namespaced operation identities. A persisted
+ * Desktop plan is a projection over the closed local registry, so it narrows
+ * discovery back to operation kinds this host can actually execute.
+ */
+export const OperationDiscoverySchema = PortableOperationDiscoverySchema.extend({
+  kind: OperationKindSchema,
+});
+
+export type GraphOperationDiscovery = z.infer<typeof OperationDiscoverySchema>;
+
+export const GRAPH_PLAN_VERSION = "slopcamera-graph-plan-v2" as const;
+export const GRAPH_COMPILER_ABI = "slopcamera-workflow-compiler-v2" as const;
+export const GRAPH_SCHEDULER_ABI = "slopcamera-workflow-scheduler-v2" as const;
+export const CODE_WORKER_ABI = "slopcamera-code-worker-abi-v4" as const;
+export const STATIC_BINDINGS_VERSION = "slopcamera-static-bindings-v1" as const;
+
+export const OPERATION_FAMILIES = [
+  "analysis",
+  "compute",
+  "derive",
+  "edit",
+  "gateway",
+  "iteration",
+  "media",
+  "project",
+  "recording",
+  "render",
+  "slopcamera",
+  "scene",
+  "spatial",
+] as const;
+
+export type OperationFamily = typeof OPERATION_FAMILIES[number];
+
+const MEDIA_TYPE_PATTERN =
+  /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/u;
+
+export const WorkflowBundleIdentitySchema = z.strictObject({
+  bundleSha256: Sha256Schema,
+  bytes: NonnegativeSafeIntegerSchema,
+  dependencyGraphSha256: Sha256Schema,
+  entrypoint: z.string().min(1).max(1_024),
+  sourceSha256: Sha256Schema,
+});
+
+export type WorkflowBundleIdentity = z.infer<typeof WorkflowBundleIdentitySchema>;
+
+export const ExternalsPolicyIdentitySchema = z.strictObject({
+  kind: z.enum(["deny-all", "allowlist"]),
+  modules: z.array(z.string().min(1).max(214)).max(256),
+  policySha256: Sha256Schema,
+});
+
+export const WorkflowRuntimeIdentitySchema = z.strictObject({
+  applicationBuild: z.string().min(1).max(160),
+  bunRevision: z.string().min(1).max(160),
+  bunVersion: z.string().min(1).max(80),
+  bundlerConfigurationSha256: Sha256Schema,
+  bundlerName: z.string().min(1).max(80),
+  bundlerRevision: z.string().min(1).max(160),
+  bundlerVersion: z.string().min(1).max(80),
+  compilerAbi: z.literal(GRAPH_COMPILER_ABI),
+  codeWorkerAbi: z.literal(CODE_WORKER_ABI),
+  externals: ExternalsPolicyIdentitySchema,
+  graphAbi: z.union([z.literal(GRAPH_ABI), z.literal(LEGACY_GRAPH_ABI)]),
+  schedulerAbi: z.literal(GRAPH_SCHEDULER_ABI),
+});
+
+export type WorkflowRuntimeIdentity = z.infer<typeof WorkflowRuntimeIdentitySchema>;
+
+export const InitialSubjectBindingSchema = z.discriminatedUnion("kind", [
+  z.strictObject({
+    descriptorSha256: Sha256Schema,
+    id: z.string().min(1).max(256),
+    kind: z.literal("spatial-project"),
+    schemaVersion: z.literal(2),
+    basis: z.strictObject({ version: z.union([z.literal(1), z.literal(2)]), sha256: Sha256Schema }),
+  }),
+  z.strictObject({
+    descriptorSha256: Sha256Schema,
+    id: z.string().min(1).max(256),
+    kind: z.literal("project"),
+    planSha256: Sha256Schema,
+    projectSha256: Sha256Schema,
+  }),
+  z.strictObject({
+    bundleSha256: Sha256Schema,
+    descriptorSha256: Sha256Schema,
+    id: z.string().min(1).max(256),
+    kind: z.literal("recording"),
+  }),
+]);
+
+export type InitialSubjectBinding = z.infer<typeof InitialSubjectBindingSchema>;
+
+export const CandidateDescriptorSchema = z.strictObject({
+  bytes: NonnegativeSafeIntegerSchema.optional(),
+  descriptorSha256: Sha256Schema,
+  id: z.string().min(1).max(256),
+  kind: z.enum(["file", "project", "recording"]),
+  mediaType: z.string().max(160).regex(MEDIA_TYPE_PATTERN).optional(),
+  sha256: Sha256Schema.optional(),
+});
+
+export type CandidateDescriptor = z.infer<typeof CandidateDescriptorSchema>;
+
+export const StaticBindingsSchema = z.strictObject({
+  candidates: z.array(CandidateDescriptorSchema).max(1_024),
+  initialSubjects: z.array(InitialSubjectBindingSchema).max(16),
+  version: z.literal(STATIC_BINDINGS_VERSION),
+});
+
+export type StaticBindings = z.infer<typeof StaticBindingsSchema>;
+
+export const GraphRegistryIdentitySchema = z.strictObject({
+  discovery: z.array(OperationDiscoverySchema).max(OPERATION_KINDS.length * 32),
+});
+
+export const UnsignedGraphPlanV1Schema = z.strictObject({
+  bundle: WorkflowBundleIdentitySchema,
+  envelope: RequirementEnvelopeSchema,
+  graph: AuthoredWorkflowGraphV1Schema,
+  limits: GraphCompilerLimitsSchema,
+  registry: GraphRegistryIdentitySchema,
+  runtime: WorkflowRuntimeIdentitySchema,
+  staticBindings: StaticBindingsSchema,
+  topologicalWaves: z.array(z.array(NodeKeySchema).min(1))
+    .max(MAX_SERIALIZED_GRAPH_NODES),
+  version: z.literal(GRAPH_PLAN_VERSION),
+  workflowInput: JsonValueSchema,
+});
+
+export type UnsignedGraphPlanV1 = z.infer<typeof UnsignedGraphPlanV1Schema>;
+
+export const GraphPlanV1Schema = UnsignedGraphPlanV1Schema.extend({
+  graphPlanSha256: Sha256Schema,
+});
+
+export type GraphPlanV1 = z.infer<typeof GraphPlanV1Schema>;

package/apps/desktop/code/planning.ts

@@ -0,0 +1,361 @@
+import { ApplicationError } from "../application/errors";
+import type { ApplicationContext } from "../application/context";
+import { openLeasedProjectSnapshot } from "../application/project-publication-lease";
+import { withSpatialProjectLease } from "../application/spatial-project-lease";
+import { spatialProjectStorePorts } from "../application/spatial-project-authority";
+import { readSpatialProjectAuthority } from "../application/spatial-project-store";
+import type { OperationRegistry } from "../application/registry";
+import { canonicalJson, sha256Hex } from "../core/canonical-json";
+import type { BuiltInWorkflow } from "../workflows";
+import {
+  STATIC_BINDINGS_VERSION,
+  StaticBindingsSchema,
+  isComputeGraphNode,
+  isOperationGraphNode,
+  type GraphPlanV1,
+  type InitialSubjectBinding,
+  type WorkflowBundleIdentity,
+} from "./contracts";
+import { compileGraphPlan } from "./compiler";
+import {
+  collectDeclaredFileCandidates,
+  collectLiteralFileCandidates,
+  mergeFileCandidateDescriptors,
+} from "./file-candidate-provenance";
+import {
+  createHostApplicationBuildIdentity,
+  createWorkflowRuntimeIdentity,
+} from "./runtime-identity";
+import {
+  checkAndBundleWorkflowSource,
+  workflowBundleContract,
+  type WorkflowSourceBundle,
+} from "./source-bundle";
+import {
+  startCodeWorker,
+  startCodeWorkerPool,
+  type CodeWorkerPool,
+  type CodeWorkerSession,
+} from "./worker-client";
+
+export const TRUSTED_CODE_WARNING = [
+  "Trusted code mode is not a sandbox.",
+  "Workflow TypeScript runs with the current user's filesystem, process, and network authority.",
+].join(" ");
+
+export interface PlanCodeWorkflowOptions {
+  readonly application: ApplicationContext;
+  readonly applicationBuild?: string;
+  readonly bunExecutable?: string;
+  readonly entryPath: string;
+  readonly registry: OperationRegistry;
+  readonly workflowInput: unknown;
+}
+
+export interface PlannedCodeWorkflow {
+  readonly bundle: WorkflowSourceBundle;
+  readonly diagnostics: {
+    readonly stderr: string;
+    readonly stdout: string;
+  };
+  readonly plan: GraphPlanV1;
+  readonly warning: string;
+}
+
+export interface PreparedCodeWorkflowRun extends PlannedCodeWorkflow {
+  startWorkerPool(
+    maximumWorkers: number,
+    options?: {
+      readonly inheritedHostResourceFileDescriptor?: number;
+    },
+  ): Promise<CodeWorkerPool>;
+  readonly worker: CodeWorkerSession;
+}
+
+export interface PlannedBuiltInWorkflow {
+  readonly bundleBytes: Uint8Array;
+  readonly plan: GraphPlanV1;
+}
+
+function projectReference(input: unknown): string | undefined {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) return undefined;
+  const project: unknown = Reflect.get(input, "project");
+  return typeof project === "string" ? project : undefined;
+}
+
+async function staticBindings(
+  application: ApplicationContext,
+  graph: GraphPlanV1["graph"],
+  workflowInput: GraphPlanV1["workflowInput"],
+) {
+  const references = new Set<string>();
+  const spatialReferences = new Set<string>();
+  for (const node of graph.nodes) {
+    if (isOperationGraphNode(node) && node.executor.operation.kind === "render.project" && node.executor.operation.version === 4) {
+      const input = node.input;
+      if (typeof input === "object" && input !== null && !Array.isArray(input) && "plan" in input) {
+        const plan = input.plan;
+        if (typeof plan === "object" && plan !== null && !Array.isArray(plan) && "projectId" in plan && typeof plan.projectId === "string") spatialReferences.add(plan.projectId);
+      }
+    }
+    if (isOperationGraphNode(node) && node.executor.operation.kind === "spatial.project.snapshot") {
+      const reference = projectReference(node.input);
+      if (reference !== undefined) spatialReferences.add(reference);
+    }
+    if (
+      !isOperationGraphNode(node)
+      || node.executor.operation.kind !== "project.snapshot"
+    ) continue;
+    const reference = projectReference(node.input);
+    if (reference !== undefined) references.add(reference);
+  }
+  const initialSubjects: InitialSubjectBinding[] = [];
+  for (const reference of [...spatialReferences].sort()) {
+    const snapshot = await withSpatialProjectLease(application, reference, async leased =>
+      await readSpatialProjectAuthority(await spatialProjectStorePorts(leased, reference)));
+    const descriptor = { id: reference, kind: "spatial-project" as const, schemaVersion: 2 as const, basis: snapshot.basis };
+    initialSubjects.push({ ...descriptor, descriptorSha256: sha256Hex(`slopcamera.workflow.spatial-project-binding/v1\0${canonicalJson(descriptor)}`) });
+  }
+  for (const reference of [...references].sort()) {
+    const snapshot = await openLeasedProjectSnapshot(application, reference);
+    initialSubjects.push({
+      descriptorSha256: sha256Hex(
+        `studio.workflow.project-binding/v1\0${canonicalJson({
+          id: snapshot.project.projectId,
+          planSha256: snapshot.generation.currentPlanSha256,
+          projectSha256: snapshot.generation.projectSha256,
+        })}`,
+      ),
+      id: snapshot.project.projectId,
+      kind: "project",
+      planSha256: snapshot.generation.currentPlanSha256,
+      projectSha256: snapshot.generation.projectSha256,
+    });
+  }
+  return StaticBindingsSchema.parse({
+    candidates: mergeFileCandidateDescriptors([
+      collectLiteralFileCandidates(graph),
+      collectDeclaredFileCandidates(workflowInput),
+    ]),
+    initialSubjects,
+    version: STATIC_BINDINGS_VERSION,
+  });
+}
+
+async function prepareCodeWorkflow(
+  options: PlanCodeWorkflowOptions,
+): Promise<PreparedCodeWorkflowRun> {
+  const applicationBuild = options.applicationBuild
+    ?? await createHostApplicationBuildIdentity(options.application);
+  const bundle = await checkAndBundleWorkflowSource({
+    allowedRoot: options.application.paths.repositoryRoot,
+    entryPath: options.entryPath,
+    ...(options.application.hostResourceLease === undefined
+      ? {}
+      : {
+          inheritedHostResourceFileDescriptor:
+            options.application.hostResourceLease.inheritedFileDescriptor,
+        }),
+  });
+  const worker = await startCodeWorker({
+    ...(options.bunExecutable === undefined ? {} : { bunExecutable: options.bunExecutable }),
+    bundle,
+    ...(options.application.hostResourceLease === undefined
+      ? {}
+      : {
+          inheritedHostResourceFileDescriptor:
+            options.application.hostResourceLease.inheritedFileDescriptor,
+        }),
+    temporaryRoot: options.application.paths.privateRoot,
+  });
+  try {
+    const built = await worker.build(options.registry, options.workflowInput);
+    const runtime = await createWorkflowRuntimeIdentity({
+      applicationBuild,
+      bundle,
+    });
+    const provisional = compileGraphPlan({
+      bundle: workflowBundleContract(bundle),
+      graph: built.graph,
+      registry: options.registry,
+      runtime,
+      workflowInput: built.input,
+    });
+    const plan = compileGraphPlan({
+      bundle: workflowBundleContract(bundle),
+      graph: built.graph,
+      registry: options.registry,
+      runtime,
+      staticBindings: await staticBindings(
+        options.application,
+        provisional.graph,
+        provisional.workflowInput,
+      ),
+      workflowInput: built.input,
+    });
+    let workerTransferred = false;
+    return {
+      bundle,
+      diagnostics: built.diagnostics,
+      plan,
+      startWorkerPool: async (maximumWorkers, poolOptions = {}) => {
+        if (workerTransferred) {
+          throw new ApplicationError(
+            "conflict",
+            "The prepared code worker was already transferred to a worker pool.",
+          );
+        }
+        workerTransferred = true;
+        return await startCodeWorkerPool({
+          ...(options.bunExecutable === undefined
+            ? {}
+            : { bunExecutable: options.bunExecutable }),
+          bundle,
+          expectedBuild: built,
+          initialWorker: {
+            build: built,
+            session: worker,
+          },
+          ...(poolOptions.inheritedHostResourceFileDescriptor === undefined
+            ? {}
+            : {
+                inheritedHostResourceFileDescriptor:
+                  poolOptions.inheritedHostResourceFileDescriptor,
+              }),
+          maximumWorkers,
+          registry: options.registry,
+          temporaryRoot: options.application.paths.privateRoot,
+          workflowInput: options.workflowInput,
+        });
+      },
+      warning: TRUSTED_CODE_WARNING,
+      worker,
+    };
+  } catch (error) {
+    await worker.close().catch(() => undefined);
+    throw error;
+  }
+}
+
+export async function prepareCodeWorkflowRun(
+  options: PlanCodeWorkflowOptions,
+): Promise<PreparedCodeWorkflowRun> {
+  return await prepareCodeWorkflow(options);
+}
+
+export async function planCodeWorkflow(
+  options: PlanCodeWorkflowOptions,
+): Promise<PlannedCodeWorkflow> {
+  const prepared = await prepareCodeWorkflow(options);
+  try {
+    return {
+      bundle: prepared.bundle,
+      diagnostics: prepared.diagnostics,
+      plan: prepared.plan,
+      warning: prepared.warning,
+    };
+  } finally {
+    await prepared.worker.close();
+  }
+}
+
+export interface PlanBuiltInWorkflowOptions {
+  readonly application: ApplicationContext;
+  readonly applicationBuild?: string;
+  readonly registry: OperationRegistry;
+  readonly workflow: BuiltInWorkflow;
+  readonly workflowInput: unknown;
+}
+
+export async function planBuiltInWorkflow(
+  options: PlanBuiltInWorkflowOptions,
+): Promise<PlannedBuiltInWorkflow> {
+  const applicationBuild = options.applicationBuild
+    ?? await createHostApplicationBuildIdentity(options.application);
+  const built = options.workflow.build(options.registry, options.workflowInput);
+  if (built.graph.nodes.some(isComputeGraphNode)) {
+    throw new ApplicationError(
+      "unsupported-plan",
+      "Built-in workflows cannot register trusted compute callbacks in a synthetic bundle.",
+    );
+  }
+  const bundleBytes = new TextEncoder().encode(`${canonicalJson({
+    id: options.workflow.id,
+    inputSchemaId: options.workflow.inputSchemaId,
+    version: options.workflow.version,
+  })}\n`);
+  const bundleSha256 = sha256Hex(new TextDecoder().decode(bundleBytes));
+  const bundle: WorkflowBundleIdentity = {
+    bundleSha256,
+    bytes: bundleBytes.byteLength,
+    dependencyGraphSha256: bundleSha256,
+    entrypoint: `builtin:${options.workflow.id}@${String(options.workflow.version)}`,
+    sourceSha256: bundleSha256,
+  };
+  const runtime = {
+    ...(await createWorkflowRuntimeIdentity({
+      applicationBuild,
+      bundle: {
+        bytes: bundleBytes,
+        dependencyGraphSha256: bundleSha256,
+        entryPath: `builtin:${options.workflow.id}`,
+        entryRelativePath: `builtin:${options.workflow.id}`,
+        externalImports: [],
+        identity: {
+          bunRevision: Bun.revision,
+          bunVersion: Bun.version,
+          format: "esm" as const,
+          minify: false as const,
+          packages: "bundle" as const,
+          schemaVersion: 1 as const,
+          sourcemap: "none" as const,
+          target: "bun" as const,
+          treeShaking: false as const,
+        },
+        importedPaths: [],
+        sha256: bundleSha256,
+        sourceSha256: bundleSha256,
+      },
+    })),
+    externals: {
+      kind: "deny-all" as const,
+      modules: [],
+      policySha256: sha256Hex("studio.workflow.builtin-externals/v1"),
+    },
+  };
+  const provisional = compileGraphPlan({
+    bundle,
+    graph: built.graph,
+    registry: options.registry,
+    runtime,
+    workflowInput: built.input,
+  });
+  return {
+    bundleBytes,
+    plan: compileGraphPlan({
+      bundle,
+      graph: built.graph,
+      registry: options.registry,
+      runtime,
+      staticBindings: await staticBindings(
+        options.application,
+        provisional.graph,
+        provisional.workflowInput,
+      ),
+      workflowInput: built.input,
+    }),
+  };
+}
+
+export function assertPlanHash(plan: GraphPlanV1, requested: string | undefined): void {
+  if (requested !== undefined && requested !== plan.graphPlanSha256) {
+    throw new ApplicationError(
+      "conflict",
+      "The requested graph plan hash does not match current code, inputs, bindings, or runtime.",
+      {
+        actual: plan.graphPlanSha256,
+        requested,
+      },
+    );
+  }
+}