@vgai/sdk 0.4.0 → 0.4.1-canary.20260715.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.4.0",
+  "version": "0.4.1-canary.20260715.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -20,7 +20,7 @@
     "./registry": "./src/registry.ts"
   },
   "dependencies": {
-    "@vgai/engine": "0.4.0",
+    "@vgai/engine": "0.4.1-canary.20260715.0",
     "playwright": "^1.58.2",
     "zod": "^4.3.6"
   }

package/src/project/index.ts

@@ -13,6 +13,7 @@ export * from './discovery-operations.js';
 export * from './entity-operations.js';
 export * from './input-map-operations.js';
 export * from './manifest-operations.js';
+export * from './provenance.js';
 export * from './scene-operations.js';
 export {
   BaseHashField,

package/src/project/provenance.ts

@@ -0,0 +1,154 @@
+import { z } from 'zod';
+
+export const PROJECT_PROVENANCE_PATH = '.vgai/provenance.json';
+
+export const ProjectProvenanceOutputSchema = z.object({
+  path: z.string(),
+  bytes: z.number().int().nonnegative(),
+  sha256: z.string().regex(/^[a-f0-9]{64}$/),
+  mediaType: z.string().optional(),
+  role: z.enum(['asset', 'prefab', 'provenance', 'other']).optional(),
+});
+
+export const ProjectProvenanceExecutionSchema = z.object({
+  mode: z.enum(['mock', 'direct', 'managed']),
+  provider: z.string(),
+  operation: z.string().optional(),
+  model: z.string().optional(),
+  requestId: z.string().optional(),
+  taskId: z.string().optional(),
+  managedJobId: z.string().optional(),
+});
+
+export const ProjectProvenanceOperationSchema = z.object({
+  createdAt: z.string().datetime(),
+  operation: z.object({
+    name: z.string(),
+    source: z.string().optional(),
+  }),
+  execution: ProjectProvenanceExecutionSchema.optional(),
+  executions: z.array(ProjectProvenanceExecutionSchema).min(2).optional(),
+  input: z.json().optional(),
+  outputs: z.array(ProjectProvenanceOutputSchema).min(1),
+});
+
+export const ProjectProvenanceDocumentSchema = z.object({
+  version: z.literal(1),
+  operations: z.record(z.string(), ProjectProvenanceOperationSchema),
+});
+
+export type ProjectProvenanceDocument = z.infer<typeof ProjectProvenanceDocumentSchema>;
+export type ProjectProvenanceOperation = z.infer<typeof ProjectProvenanceOperationSchema>;
+export type ProjectProvenanceExecution = z.infer<typeof ProjectProvenanceExecutionSchema>;
+
+export const ProjectAttributionEntrySchema = z.object({
+  key: z.string(),
+  name: z.string().optional(),
+  source: z.string().optional(),
+  sourceUrl: z.string().url().optional(),
+  author: z.string(),
+  license: z.string(),
+  text: z.string(),
+  operationIds: z.array(z.string()),
+  outputPaths: z.array(z.string()),
+});
+
+export const ProjectAttributionReportSchema = z.object({
+  version: z.literal(1),
+  entries: z.array(ProjectAttributionEntrySchema),
+});
+
+export type ProjectAttributionEntry = z.infer<typeof ProjectAttributionEntrySchema>;
+export type ProjectAttributionReport = z.infer<typeof ProjectAttributionReportSchema>;
+
+export function emptyProjectProvenanceDocument(): ProjectProvenanceDocument {
+  return { version: 1, operations: {} };
+}
+
+function objectRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function stringField(record: Record<string, unknown>, key: string): string | undefined {
+  const value = record[key];
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function attributionEntry(
+  operationId: string,
+  operation: ProjectProvenanceOperation,
+): ProjectAttributionEntry | null {
+  const input = objectRecord(operation.input);
+  if (!input) return null;
+  const nested = objectRecord(input['attribution']) ?? {};
+  const author = stringField(nested, 'author') ?? stringField(input, 'author');
+  const license = stringField(nested, 'license') ?? stringField(input, 'license');
+  if (!author || !license) return null;
+  const name = stringField(nested, 'name') ?? stringField(input, 'name');
+  const source = stringField(nested, 'source') ?? stringField(input, 'source');
+  const sourceUrl = stringField(nested, 'sourceUrl') ?? stringField(input, 'sourceUrl');
+  const text = stringField(nested, 'text') ?? `${name ? `${name} by ` : ''}${author} (${license})`;
+  const key = JSON.stringify([sourceUrl ?? '', author, license, text]);
+  return ProjectAttributionEntrySchema.parse({
+    key,
+    ...(name ? { name } : {}),
+    ...(source ? { source } : {}),
+    ...(sourceUrl ? { sourceUrl } : {}),
+    author,
+    license,
+    text,
+    operationIds: [operationId],
+    outputPaths: operation.outputs
+      .filter((output) => output.role !== 'provenance')
+      .map((output) => output.path),
+  });
+}
+
+/**
+ * Project credits are a projection of central provenance, never another
+ * persisted ledger or a set of per-asset files.
+ */
+export function deriveProjectAttributionReport(
+  document: ProjectProvenanceDocument,
+): ProjectAttributionReport {
+  const grouped = new Map<string, ProjectAttributionEntry>();
+  for (const [operationId, operation] of Object.entries(document.operations)) {
+    const entry = attributionEntry(operationId, operation);
+    if (!entry) continue;
+    const prior = grouped.get(entry.key);
+    if (!prior) {
+      grouped.set(entry.key, entry);
+      continue;
+    }
+    prior.operationIds.push(...entry.operationIds);
+    prior.outputPaths.push(...entry.outputPaths);
+  }
+  const entries = [...grouped.values()]
+    .map((entry) => ({
+      ...entry,
+      operationIds: [...new Set(entry.operationIds)].sort(),
+      outputPaths: [...new Set(entry.outputPaths)].sort(),
+    }))
+    .sort(
+      (left, right) => left.text.localeCompare(right.text) || left.key.localeCompare(right.key),
+    );
+  return ProjectAttributionReportSchema.parse({ version: 1, entries });
+}
+
+/** Deterministic human-readable projection of the machine report. */
+export function formatProjectAttributionMarkdown(report: ProjectAttributionReport): string {
+  const sections = report.entries.map((entry) => {
+    const heading = entry.name ?? entry.text;
+    return [
+      `## ${heading}`,
+      '',
+      entry.text,
+      '',
+      `Author: ${entry.author}  `,
+      `License: ${entry.license}${entry.sourceUrl ? `  \nSource: ${entry.sourceUrl}` : ''}`,
+    ].join('\n');
+  });
+  return `# Asset attribution\n${sections.length > 0 ? `\n${sections.join('\n\n')}` : '\nNo attributed project assets are currently present.'}\n`;
+}

package/src/types.ts

@@ -68,6 +68,30 @@ export interface ProjectGeneratedOutput {
   files: ProjectGeneratedOutputFile[];
   totalBytes: number;
   dryRun: boolean;
+  /** Host-created logical record in .vgai/provenance.json; absent for dry runs. */
+  provenanceOperationId?: string;
+}
+
+export interface ProjectProviderExecution {
+  mode: 'mock' | 'direct' | 'managed';
+  provider: string;
+  operation?: string;
+  model?: string;
+  requestId?: string;
+  taskId?: string;
+  managedJobId?: string;
+}
+
+/** Facts the operation host already owns and stamps onto every committed batch. */
+export interface ProjectOutputProvenanceContext {
+  operationName: string;
+  operationSource?: string;
+  /** Sanitized facts for a single provider execution. */
+  execution?: ProjectProviderExecution;
+  /** Ordered facts for a native multi-task pipeline that produced one output batch. */
+  executions?: readonly ProjectProviderExecution[];
+  /** Schema-validated, JSON-safe operation input. */
+  input?: unknown;
 }
 
 /**