@deepnote/blocks 1.3.5 → 1.4.0

package/dist/index.cjs

@@ -32,7 +32,10 @@ ts_dedent = __toESM(ts_dedent);
 const deepnoteBlockSchema = zod.z.object({
 	blockGroup: zod.z.string().optional(),
 	content: zod.z.string().optional(),
+	contentHash: zod.z.string().regex(/^(md5|sha256):[a-f0-9]+$/i).optional(),
 	executionCount: zod.z.number().optional(),
+	executionFinishedAt: zod.z.string().datetime().optional(),
+	executionStartedAt: zod.z.string().datetime().optional(),
 	id: zod.z.string(),
 	metadata: zod.z.record(zod.z.any()).optional(),
 	outputs: zod.z.array(zod.z.any()).optional(),
@@ -40,7 +43,49 @@ const deepnoteBlockSchema = zod.z.object({
 	type: zod.z.string(),
 	version: zod.z.number().optional()
 });
+const environmentSchema = zod.z.object({
+	customImage: zod.z.string().optional(),
+	hash: zod.z.string().optional(),
+	packages: zod.z.record(zod.z.string()).optional(),
+	platform: zod.z.string().optional(),
+	python: zod.z.object({
+		environment: zod.z.enum([
+			"uv",
+			"conda",
+			"venv",
+			"poetry",
+			"system"
+		]).optional(),
+		version: zod.z.string().optional()
+	}).optional()
+}).optional();
+const executionSummarySchema = zod.z.object({
+	blocksExecuted: zod.z.number().int().nonnegative().optional(),
+	blocksFailed: zod.z.number().int().nonnegative().optional(),
+	blocksSucceeded: zod.z.number().int().nonnegative().optional(),
+	totalDurationMs: zod.z.number().nonnegative().optional()
+}).optional();
+const executionErrorSchema = zod.z.object({
+	message: zod.z.string().optional(),
+	name: zod.z.string().optional(),
+	traceback: zod.z.array(zod.z.string()).optional()
+}).optional();
+const executionSchema = zod.z.object({
+	error: executionErrorSchema,
+	finishedAt: zod.z.string().datetime().optional(),
+	inputs: zod.z.record(zod.z.unknown()).optional(),
+	startedAt: zod.z.string().datetime().optional(),
+	summary: executionSummarySchema,
+	triggeredBy: zod.z.enum([
+		"user",
+		"schedule",
+		"api",
+		"ci"
+	]).optional()
+}).optional();
 const deepnoteFileSchema = zod.z.object({
+	environment: environmentSchema,
+	execution: executionSchema,
 	metadata: zod.z.object({
 		checksum: zod.z.string().optional(),
 		createdAt: zod.z.string(),
@@ -78,9 +123,88 @@ const deepnoteFileSchema = zod.z.object({
 
 //#endregion
 //#region src/deserialize-file/parse-yaml.ts
+/**
+* Validates UTF-8 encoding from raw bytes before decoding to string.
+* This is the proper way to validate UTF-8 - check BEFORE decoding.
+*
+* @param bytes - Raw file bytes as Uint8Array
+* @returns Decoded UTF-8 string without BOM
+* @throws Error if BOM detected or invalid UTF-8 encoding
+*
+* @example
+* ```typescript
+* const bytes = await fs.readFile('file.deepnote') // Returns Buffer/Uint8Array
+* const yamlContent = decodeUtf8NoBom(bytes)
+* const parsed = parseYaml(yamlContent)
+* ```
+*/
+function decodeUtf8NoBom(bytes) {
+	if (bytes.length >= 3 && bytes[0] === 239 && bytes[1] === 187 && bytes[2] === 191) throw new Error("UTF-8 BOM detected in Deepnote file - files must be UTF-8 without BOM");
+	try {
+		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch {
+		throw new Error("Invalid UTF-8 encoding detected in Deepnote file");
+	}
+}
+/**
+* Validates that a string doesn't start with BOM.
+* Note: This is a fallback when only a string is available.
+* By the time we have a JS string, invalid UTF-8 has already been handled during decoding.
+* For proper UTF-8 validation, use decodeUtf8NoBom() on raw bytes before decoding.
+*
+* @param yamlContent - Already-decoded YAML string
+* @throws Error if BOM prefix detected
+*/
+function validateNoBomPrefix(yamlContent) {
+	if (yamlContent.charCodeAt(0) === 65279) throw new Error("UTF-8 BOM detected in Deepnote file - files must be UTF-8 without BOM");
+}
+/**
+* Validates that the YAML document doesn't contain prohibited features:
+* - No anchors/aliases (&anchor, *alias)
+* - No merge keys (<<)
+* - No custom tags (!tag)
+*/
+function validateYamlStructure(yamlContent) {
+	if (/(?:^|\n)\s*(?:-\s+|[\w-]+:\s*)&\w+/.test(yamlContent)) throw new Error("YAML anchors (&) are not allowed in Deepnote files");
+	if (/(?:^|\n)\s*(?:-\s+|[\w-]+:\s*)\*\w+/.test(yamlContent)) throw new Error("YAML aliases (*) are not allowed in Deepnote files");
+	if (/<<:/.test(yamlContent)) throw new Error("YAML merge keys (<<) are not allowed in Deepnote files");
+	const matches = yamlContent.match(/(?:^|\n)\s*(?:-\s+|[\w-]+:\s*)(![\w/-]+)/gm);
+	if (matches) {
+		const tags = matches.map((m) => m.match(/(![\w/-]+)/)?.[1]).filter(Boolean);
+		if (tags.length > 0) throw new Error(`YAML tags are not allowed in Deepnote files: ${tags.join(", ")}`);
+	}
+}
+/**
+* Parse and validate YAML document in a single pass.
+* Checks for duplicate keys and other parsing errors, then converts to JavaScript object.
+*/
+function parseAndValidate(yamlContent) {
+	const doc = (0, yaml.parseDocument)(yamlContent, {
+		strict: true,
+		uniqueKeys: true,
+		version: "1.2"
+	});
+	if (doc.errors.length > 0) {
+		const duplicateKeyError = doc.errors.find((err) => err.message.includes("duplicate") || err.message.includes("key"));
+		if (duplicateKeyError) throw new Error(`Duplicate keys detected in Deepnote file: ${duplicateKeyError.message}`);
+		throw new Error(`YAML parsing error: ${doc.errors[0].message}`);
+	}
+	return doc.toJS();
+}
+/**
+* Parse YAML content with strict validation rules:
+* - YAML 1.2 only
+* - UTF-8 only
+* - No duplicate keys
+* - No anchors/aliases/merge keys
+* - No custom tags
+* - Explicit typing enforced by schema
+*/
 function parseYaml(yamlContent) {
 	try {
-		return (0, yaml.parse)(yamlContent);
+		validateNoBomPrefix(yamlContent);
+		validateYamlStructure(yamlContent);
+		return parseAndValidate(yamlContent);
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		throw new Error(`Failed to parse Deepnote file: ${message}`);
@@ -593,6 +717,12 @@ function createPythonCode(block, executionContext) {
 //#endregion
 exports.createMarkdown = createMarkdown;
 exports.createPythonCode = createPythonCode;
+exports.decodeUtf8NoBom = decodeUtf8NoBom;
 exports.deepnoteBlockSchema = deepnoteBlockSchema;
+exports.deepnoteFileSchema = deepnoteFileSchema;
 exports.deserializeDeepnoteFile = deserializeDeepnoteFile;
+exports.environmentSchema = environmentSchema;
+exports.executionErrorSchema = executionErrorSchema;
+exports.executionSchema = executionSchema;
+exports.executionSummarySchema = executionSummarySchema;
 exports.stripMarkdown = stripMarkdown;

package/dist/index.d.cts

@@ -30,7 +30,10 @@ interface TableState {
 declare const deepnoteBlockSchema: z.ZodObject<{
   blockGroup: z.ZodOptional<z.ZodString>;
   content: z.ZodOptional<z.ZodString>;
+  contentHash: z.ZodOptional<z.ZodString>;
   executionCount: z.ZodOptional<z.ZodNumber>;
+  executionFinishedAt: z.ZodOptional<z.ZodString>;
+  executionStartedAt: z.ZodOptional<z.ZodString>;
   id: z.ZodString;
   metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
   outputs: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
@@ -43,7 +46,10 @@ declare const deepnoteBlockSchema: z.ZodObject<{
   sortingKey: string;
   blockGroup?: string | undefined;
   content?: string | undefined;
+  contentHash?: string | undefined;
   executionCount?: number | undefined;
+  executionFinishedAt?: string | undefined;
+  executionStartedAt?: string | undefined;
   metadata?: Record<string, any> | undefined;
   outputs?: any[] | undefined;
   version?: number | undefined;
@@ -53,13 +59,251 @@ declare const deepnoteBlockSchema: z.ZodObject<{
   sortingKey: string;
   blockGroup?: string | undefined;
   content?: string | undefined;
+  contentHash?: string | undefined;
   executionCount?: number | undefined;
+  executionFinishedAt?: string | undefined;
+  executionStartedAt?: string | undefined;
   metadata?: Record<string, any> | undefined;
   outputs?: any[] | undefined;
   version?: number | undefined;
 }>;
 type DeepnoteBlock = z.infer<typeof deepnoteBlockSchema>;
+declare const environmentSchema: z.ZodOptional<z.ZodObject<{
+  customImage: z.ZodOptional<z.ZodString>;
+  hash: z.ZodOptional<z.ZodString>;
+  packages: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  platform: z.ZodOptional<z.ZodString>;
+  python: z.ZodOptional<z.ZodObject<{
+    environment: z.ZodOptional<z.ZodEnum<["uv", "conda", "venv", "poetry", "system"]>>;
+    version: z.ZodOptional<z.ZodString>;
+  }, "strip", z.ZodTypeAny, {
+    version?: string | undefined;
+    environment?: "uv" | "conda" | "venv" | "poetry" | "system" | undefined;
+  }, {
+    version?: string | undefined;
+    environment?: "uv" | "conda" | "venv" | "poetry" | "system" | undefined;
+  }>>;
+}, "strip", z.ZodTypeAny, {
+  customImage?: string | undefined;
+  hash?: string | undefined;
+  packages?: Record<string, string> | undefined;
+  platform?: string | undefined;
+  python?: {
+    version?: string | undefined;
+    environment?: "uv" | "conda" | "venv" | "poetry" | "system" | undefined;
+  } | undefined;
+}, {
+  customImage?: string | undefined;
+  hash?: string | undefined;
+  packages?: Record<string, string> | undefined;
+  platform?: string | undefined;
+  python?: {
+    version?: string | undefined;
+    environment?: "uv" | "conda" | "venv" | "poetry" | "system" | undefined;
+  } | undefined;
+}>>;
+type Environment = z.infer<typeof environmentSchema>;
+declare const executionSummarySchema: z.ZodOptional<z.ZodObject<{
+  blocksExecuted: z.ZodOptional<z.ZodNumber>;
+  blocksFailed: z.ZodOptional<z.ZodNumber>;
+  blocksSucceeded: z.ZodOptional<z.ZodNumber>;
+  totalDurationMs: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+  blocksExecuted?: number | undefined;
+  blocksFailed?: number | undefined;
+  blocksSucceeded?: number | undefined;
+  totalDurationMs?: number | undefined;
+}, {
+  blocksExecuted?: number | undefined;
+  blocksFailed?: number | undefined;
+  blocksSucceeded?: number | undefined;
+  totalDurationMs?: number | undefined;
+}>>;
+type ExecutionSummary = z.infer<typeof executionSummarySchema>;
+declare const executionErrorSchema: z.ZodOptional<z.ZodObject<{
+  message: z.ZodOptional<z.ZodString>;
+  name: z.ZodOptional<z.ZodString>;
+  traceback: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+  message?: string | undefined;
+  name?: string | undefined;
+  traceback?: string[] | undefined;
+}, {
+  message?: string | undefined;
+  name?: string | undefined;
+  traceback?: string[] | undefined;
+}>>;
+type ExecutionError = z.infer<typeof executionErrorSchema>;
+declare const executionSchema: z.ZodOptional<z.ZodObject<{
+  error: z.ZodOptional<z.ZodObject<{
+    message: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    traceback: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+  }, "strip", z.ZodTypeAny, {
+    message?: string | undefined;
+    name?: string | undefined;
+    traceback?: string[] | undefined;
+  }, {
+    message?: string | undefined;
+    name?: string | undefined;
+    traceback?: string[] | undefined;
+  }>>;
+  finishedAt: z.ZodOptional<z.ZodString>;
+  inputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  startedAt: z.ZodOptional<z.ZodString>;
+  summary: z.ZodOptional<z.ZodObject<{
+    blocksExecuted: z.ZodOptional<z.ZodNumber>;
+    blocksFailed: z.ZodOptional<z.ZodNumber>;
+    blocksSucceeded: z.ZodOptional<z.ZodNumber>;
+    totalDurationMs: z.ZodOptional<z.ZodNumber>;
+  }, "strip", z.ZodTypeAny, {
+    blocksExecuted?: number | undefined;
+    blocksFailed?: number | undefined;
+    blocksSucceeded?: number | undefined;
+    totalDurationMs?: number | undefined;
+  }, {
+    blocksExecuted?: number | undefined;
+    blocksFailed?: number | undefined;
+    blocksSucceeded?: number | undefined;
+    totalDurationMs?: number | undefined;
+  }>>;
+  triggeredBy: z.ZodOptional<z.ZodEnum<["user", "schedule", "api", "ci"]>>;
+}, "strip", z.ZodTypeAny, {
+  error?: {
+    message?: string | undefined;
+    name?: string | undefined;
+    traceback?: string[] | undefined;
+  } | undefined;
+  finishedAt?: string | undefined;
+  inputs?: Record<string, unknown> | undefined;
+  startedAt?: string | undefined;
+  summary?: {
+    blocksExecuted?: number | undefined;
+    blocksFailed?: number | undefined;
+    blocksSucceeded?: number | undefined;
+    totalDurationMs?: number | undefined;
+  } | undefined;
+  triggeredBy?: "user" | "schedule" | "api" | "ci" | undefined;
+}, {
+  error?: {
+    message?: string | undefined;
+    name?: string | undefined;
+    traceback?: string[] | undefined;
+  } | undefined;
+  finishedAt?: string | undefined;
+  inputs?: Record<string, unknown> | undefined;
+  startedAt?: string | undefined;
+  summary?: {
+    blocksExecuted?: number | undefined;
+    blocksFailed?: number | undefined;
+    blocksSucceeded?: number | undefined;
+    totalDurationMs?: number | undefined;
+  } | undefined;
+  triggeredBy?: "user" | "schedule" | "api" | "ci" | undefined;
+}>>;
+type Execution = z.infer<typeof executionSchema>;
 declare const deepnoteFileSchema: z.ZodObject<{
+  environment: z.ZodOptional<z.ZodObject<{
+    customImage: z.ZodOptional<z.ZodString>;
+    hash: z.ZodOptional<z.ZodString>;
+    packages: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    platform: z.ZodOptional<z.ZodString>;
+    python: z.ZodOptional<z.ZodObject<{
+      environment: z.ZodOptional<z.ZodEnum<["uv", "conda", "venv", "poetry", "system"]>>;
+      version: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+      version?: string | undefined;
+      environment?: "uv" | "conda" | "venv" | "poetry" | "system" | undefined;
+    }, {
+      version?: string | undefined;
+      environment?: "uv" | "conda" | "venv" | "poetry" | "system" | undefined;
+    }>>;
+  }, "strip", z.ZodTypeAny, {
+    customImage?: string | undefined;
+    hash?: string | undefined;
+    packages?: Record<string, string> | undefined;
+    platform?: string | undefined;
+    python?: {
+      version?: string | undefined;
+      environment?: "uv" | "conda" | "venv" | "poetry" | "system" | undefined;
+    } | undefined;
+  }, {
+    customImage?: string | undefined;
+    hash?: string | undefined;
+    packages?: Record<string, string> | undefined;
+    platform?: string | undefined;
+    python?: {
+      version?: string | undefined;
+      environment?: "uv" | "conda" | "venv" | "poetry" | "system" | undefined;
+    } | undefined;
+  }>>;
+  execution: z.ZodOptional<z.ZodObject<{
+    error: z.ZodOptional<z.ZodObject<{
+      message: z.ZodOptional<z.ZodString>;
+      name: z.ZodOptional<z.ZodString>;
+      traceback: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+      message?: string | undefined;
+      name?: string | undefined;
+      traceback?: string[] | undefined;
+    }, {
+      message?: string | undefined;
+      name?: string | undefined;
+      traceback?: string[] | undefined;
+    }>>;
+    finishedAt: z.ZodOptional<z.ZodString>;
+    inputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    startedAt: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodObject<{
+      blocksExecuted: z.ZodOptional<z.ZodNumber>;
+      blocksFailed: z.ZodOptional<z.ZodNumber>;
+      blocksSucceeded: z.ZodOptional<z.ZodNumber>;
+      totalDurationMs: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+      blocksExecuted?: number | undefined;
+      blocksFailed?: number | undefined;
+      blocksSucceeded?: number | undefined;
+      totalDurationMs?: number | undefined;
+    }, {
+      blocksExecuted?: number | undefined;
+      blocksFailed?: number | undefined;
+      blocksSucceeded?: number | undefined;
+      totalDurationMs?: number | undefined;
+    }>>;
+    triggeredBy: z.ZodOptional<z.ZodEnum<["user", "schedule", "api", "ci"]>>;
+  }, "strip", z.ZodTypeAny, {
+    error?: {
+      message?: string | undefined;
+      name?: string | undefined;
+      traceback?: string[] | undefined;
+    } | undefined;
+    finishedAt?: string | undefined;
+    inputs?: Record<string, unknown> | undefined;
+    startedAt?: string | undefined;
+    summary?: {
+      blocksExecuted?: number | undefined;
+      blocksFailed?: number | undefined;
+      blocksSucceeded?: number | undefined;
+      totalDurationMs?: number | undefined;
+    } | undefined;
+    triggeredBy?: "user" | "schedule" | "api" | "ci" | undefined;
+  }, {
+    error?: {
+      message?: string | undefined;
+      name?: string | undefined;
+      traceback?: string[] | undefined;
+    } | undefined;
+    finishedAt?: string | undefined;
+    inputs?: Record<string, unknown> | undefined;
+    startedAt?: string | undefined;
+    summary?: {
+      blocksExecuted?: number | undefined;
+      blocksFailed?: number | undefined;
+      blocksSucceeded?: number | undefined;
+      totalDurationMs?: number | undefined;
+    } | undefined;
+    triggeredBy?: "user" | "schedule" | "api" | "ci" | undefined;
+  }>>;
   metadata: z.ZodObject<{
     checksum: z.ZodOptional<z.ZodString>;
     createdAt: z.ZodString;
@@ -97,7 +341,10 @@ declare const deepnoteFileSchema: z.ZodObject<{
       blocks: z.ZodArray<z.ZodObject<{
         blockGroup: z.ZodOptional<z.ZodString>;
         content: z.ZodOptional<z.ZodString>;
+        contentHash: z.ZodOptional<z.ZodString>;
         executionCount: z.ZodOptional<z.ZodNumber>;
+        executionFinishedAt: z.ZodOptional<z.ZodString>;
+        executionStartedAt: z.ZodOptional<z.ZodString>;
         id: z.ZodString;
         metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
         outputs: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
@@ -110,7 +357,10 @@ declare const deepnoteFileSchema: z.ZodObject<{
         sortingKey: string;
         blockGroup?: string | undefined;
         content?: string | undefined;
+        contentHash?: string | undefined;
         executionCount?: number | undefined;
+        executionFinishedAt?: string | undefined;
+        executionStartedAt?: string | undefined;
         metadata?: Record<string, any> | undefined;
         outputs?: any[] | undefined;
         version?: number | undefined;
@@ -120,7 +370,10 @@ declare const deepnoteFileSchema: z.ZodObject<{
         sortingKey: string;
         blockGroup?: string | undefined;
         content?: string | undefined;
+        contentHash?: string | undefined;
         executionCount?: number | undefined;
+        executionFinishedAt?: string | undefined;
+        executionStartedAt?: string | undefined;
         metadata?: Record<string, any> | undefined;
         outputs?: any[] | undefined;
         version?: number | undefined;
@@ -139,7 +392,10 @@ declare const deepnoteFileSchema: z.ZodObject<{
         sortingKey: string;
         blockGroup?: string | undefined;
         content?: string | undefined;
+        contentHash?: string | undefined;
         executionCount?: number | undefined;
+        executionFinishedAt?: string | undefined;
+        executionStartedAt?: string | undefined;
         metadata?: Record<string, any> | undefined;
         outputs?: any[] | undefined;
         version?: number | undefined;
@@ -156,7 +412,10 @@ declare const deepnoteFileSchema: z.ZodObject<{
         sortingKey: string;
         blockGroup?: string | undefined;
         content?: string | undefined;
+        contentHash?: string | undefined;
         executionCount?: number | undefined;
+        executionFinishedAt?: string | undefined;
+        executionStartedAt?: string | undefined;
         metadata?: Record<string, any> | undefined;
         outputs?: any[] | undefined;
         version?: number | undefined;
@@ -166,6 +425,10 @@ declare const deepnoteFileSchema: z.ZodObject<{
       workingDirectory?: string | undefined;
     }>, "many">;
     settings: z.ZodOptional<z.ZodObject<{
+      /**
+       * @deprecated Use top-level `environment` instead.
+       * This field is kept for backward compatibility.
+       */
       environment: z.ZodOptional<z.ZodObject<{
         customImage: z.ZodOptional<z.ZodString>;
         pythonVersion: z.ZodOptional<z.ZodString>;
@@ -205,7 +468,10 @@ declare const deepnoteFileSchema: z.ZodObject<{
         sortingKey: string;
         blockGroup?: string | undefined;
         content?: string | undefined;
+        contentHash?: string | undefined;
         executionCount?: number | undefined;
+        executionFinishedAt?: string | undefined;
+        executionStartedAt?: string | undefined;
         metadata?: Record<string, any> | undefined;
         outputs?: any[] | undefined;
         version?: number | undefined;
@@ -240,7 +506,10 @@ declare const deepnoteFileSchema: z.ZodObject<{
         sortingKey: string;
         blockGroup?: string | undefined;
         content?: string | undefined;
+        contentHash?: string | undefined;
         executionCount?: number | undefined;
+        executionFinishedAt?: string | undefined;
+        executionStartedAt?: string | undefined;
         metadata?: Record<string, any> | undefined;
         outputs?: any[] | undefined;
         version?: number | undefined;
@@ -285,7 +554,10 @@ declare const deepnoteFileSchema: z.ZodObject<{
         sortingKey: string;
         blockGroup?: string | undefined;
         content?: string | undefined;
+        contentHash?: string | undefined;
         executionCount?: number | undefined;
+        executionFinishedAt?: string | undefined;
+        executionStartedAt?: string | undefined;
         metadata?: Record<string, any> | undefined;
         outputs?: any[] | undefined;
         version?: number | undefined;
@@ -309,6 +581,33 @@ declare const deepnoteFileSchema: z.ZodObject<{
       sqlCacheMaxAge?: number | undefined;
     } | undefined;
   };
+  environment?: {
+    customImage?: string | undefined;
+    hash?: string | undefined;
+    packages?: Record<string, string> | undefined;
+    platform?: string | undefined;
+    python?: {
+      version?: string | undefined;
+      environment?: "uv" | "conda" | "venv" | "poetry" | "system" | undefined;
+    } | undefined;
+  } | undefined;
+  execution?: {
+    error?: {
+      message?: string | undefined;
+      name?: string | undefined;
+      traceback?: string[] | undefined;
+    } | undefined;
+    finishedAt?: string | undefined;
+    inputs?: Record<string, unknown> | undefined;
+    startedAt?: string | undefined;
+    summary?: {
+      blocksExecuted?: number | undefined;
+      blocksFailed?: number | undefined;
+      blocksSucceeded?: number | undefined;
+      totalDurationMs?: number | undefined;
+    } | undefined;
+    triggeredBy?: "user" | "schedule" | "api" | "ci" | undefined;
+  } | undefined;
 }, {
   metadata: {
     createdAt: string;
@@ -329,7 +628,10 @@ declare const deepnoteFileSchema: z.ZodObject<{
         sortingKey: string;
         blockGroup?: string | undefined;
         content?: string | undefined;
+        contentHash?: string | undefined;
         executionCount?: number | undefined;
+        executionFinishedAt?: string | undefined;
+        executionStartedAt?: string | undefined;
         metadata?: Record<string, any> | undefined;
         outputs?: any[] | undefined;
         version?: number | undefined;
@@ -353,6 +655,33 @@ declare const deepnoteFileSchema: z.ZodObject<{
       sqlCacheMaxAge?: number | undefined;
     } | undefined;
   };
+  environment?: {
+    customImage?: string | undefined;
+    hash?: string | undefined;
+    packages?: Record<string, string> | undefined;
+    platform?: string | undefined;
+    python?: {
+      version?: string | undefined;
+      environment?: "uv" | "conda" | "venv" | "poetry" | "system" | undefined;
+    } | undefined;
+  } | undefined;
+  execution?: {
+    error?: {
+      message?: string | undefined;
+      name?: string | undefined;
+      traceback?: string[] | undefined;
+    } | undefined;
+    finishedAt?: string | undefined;
+    inputs?: Record<string, unknown> | undefined;
+    startedAt?: string | undefined;
+    summary?: {
+      blocksExecuted?: number | undefined;
+      blocksFailed?: number | undefined;
+      blocksSucceeded?: number | undefined;
+      totalDurationMs?: number | undefined;
+    } | undefined;
+    triggeredBy?: "user" | "schedule" | "api" | "ci" | undefined;
+  } | undefined;
 }>;
 type DeepnoteFile = z.infer<typeof deepnoteFileSchema>;
 //#endregion
@@ -362,6 +691,24 @@ type DeepnoteFile = z.infer<typeof deepnoteFileSchema>;
  */
 declare function deserializeDeepnoteFile(yamlContent: string): DeepnoteFile;
 //#endregion
+//#region src/deserialize-file/parse-yaml.d.ts
+/**
+ * Validates UTF-8 encoding from raw bytes before decoding to string.
+ * This is the proper way to validate UTF-8 - check BEFORE decoding.
+ *
+ * @param bytes - Raw file bytes as Uint8Array
+ * @returns Decoded UTF-8 string without BOM
+ * @throws Error if BOM detected or invalid UTF-8 encoding
+ *
+ * @example
+ * ```typescript
+ * const bytes = await fs.readFile('file.deepnote') // Returns Buffer/Uint8Array
+ * const yamlContent = decodeUtf8NoBom(bytes)
+ * const parsed = parseYaml(yamlContent)
+ * ```
+ */
+declare function decodeUtf8NoBom(bytes: Uint8Array): string;
+//#endregion
 //#region src/markdown.d.ts
 declare function createMarkdown(block: DeepnoteBlock): string;
 declare function stripMarkdown(block: DeepnoteBlock): string;
@@ -378,4 +725,4 @@ interface ButtonExecutionContext {
 //#region src/python-code.d.ts
 declare function createPythonCode(block: DeepnoteBlock, executionContext?: ButtonExecutionContext): string;
 //#endregion
-export { type DeepnoteBlock, type DeepnoteFile, type TableState, createMarkdown, createPythonCode, deepnoteBlockSchema, deserializeDeepnoteFile, stripMarkdown };
+export { type DeepnoteBlock, type DeepnoteFile, type Environment, type Execution, type ExecutionError, type ExecutionSummary, type TableState, createMarkdown, createPythonCode, decodeUtf8NoBom, deepnoteBlockSchema, deepnoteFileSchema, deserializeDeepnoteFile, environmentSchema, executionErrorSchema, executionSchema, executionSummarySchema, stripMarkdown };

package/dist/index.d.ts

@@ -30,7 +30,10 @@ interface TableState {
 declare const deepnoteBlockSchema: z.ZodObject<{
   blockGroup: z.ZodOptional<z.ZodString>;
   content: z.ZodOptional<z.ZodString>;
+  contentHash: z.ZodOptional<z.ZodString>;
   executionCount: z.ZodOptional<z.ZodNumber>;
+  executionFinishedAt: z.ZodOptional<z.ZodString>;
+  executionStartedAt: z.ZodOptional<z.ZodString>;
   id: z.ZodString;
   metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
   outputs: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
@@ -43,7 +46,10 @@ declare const deepnoteBlockSchema: z.ZodObject<{
   sortingKey: string;
   blockGroup?: string | undefined;
   content?: string | undefined;
+  contentHash?: string | undefined;
   executionCount?: number | undefined;
+  executionFinishedAt?: string | undefined;
+  executionStartedAt?: string | undefined;
   metadata?: Record<string, any> | undefined;
   outputs?: any[] | undefined;
   version?: number | undefined;
@@ -53,13 +59,251 @@ declare const deepnoteBlockSchema: z.ZodObject<{
   sortingKey: string;
   blockGroup?: string | undefined;
   content?: string | undefined;
+  contentHash?: string | undefined;
   executionCount?: number | undefined;
+  executionFinishedAt?: string | undefined;
+  executionStartedAt?: string | undefined;
   metadata?: Record<string, any> | undefined;
   outputs?: any[] | undefined;
   version?: number | undefined;
 }>;
 type DeepnoteBlock = z.infer<typeof deepnoteBlockSchema>;
+declare const environmentSchema: z.ZodOptional<z.ZodObject<{
+  customImage: z.ZodOptional<z.ZodString>;
+  hash: z.ZodOptional<z.ZodString>;
+  packages: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  platform: z.ZodOptional<z.ZodString>;
+  python: z.ZodOptional<z.ZodObject<{
+    environment: z.ZodOptional<z.ZodEnum<["uv", "conda", "venv", "poetry", "system"]>>;
+    version: z.ZodOptional<z.ZodString>;
+  }, "strip", z.ZodTypeAny, {
+    version?: string | undefined;
+    environment?: "uv" | "conda" | "venv" | "poetry" | "system" | undefined;
+  }, {
+    version?: string | undefined;
+    environment?: "uv" | "conda" | "venv" | "poetry" | "system" | undefined;
+  }>>;
+}, "strip", z.ZodTypeAny, {
+  customImage?: string | undefined;
+  hash?: string | undefined;
+  packages?: Record<string, string> | undefined;
+  platform?: string | undefined;
+  python?: {
+    version?: string | undefined;
+    environment?: "uv" | "conda" | "venv" | "poetry" | "system" | undefined;
+  } | undefined;
+}, {
+  customImage?: string | undefined;
+  hash?: string | undefined;
+  packages?: Record<string, string> | undefined;
+  platform?: string | undefined;
+  python?: {
+    version?: string | undefined;
+    environment?: "uv" | "conda" | "venv" | "poetry" | "system" | undefined;
+  } | undefined;
+}>>;
+type Environment = z.infer<typeof environmentSchema>;
+declare const executionSummarySchema: z.ZodOptional<z.ZodObject<{
+  blocksExecuted: z.ZodOptional<z.ZodNumber>;
+  blocksFailed: z.ZodOptional<z.ZodNumber>;
+  blocksSucceeded: z.ZodOptional<z.ZodNumber>;
+  totalDurationMs: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+  blocksExecuted?: number | undefined;
+  blocksFailed?: number | undefined;
+  blocksSucceeded?: number | undefined;
+  totalDurationMs?: number | undefined;
+}, {
+  blocksExecuted?: number | undefined;
+  blocksFailed?: number | undefined;
+  blocksSucceeded?: number | undefined;
+  totalDurationMs?: number | undefined;
+}>>;
+type ExecutionSummary = z.infer<typeof executionSummarySchema>;
+declare const executionErrorSchema: z.ZodOptional<z.ZodObject<{
+  message: z.ZodOptional<z.ZodString>;
+  name: z.ZodOptional<z.ZodString>;
+  traceback: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+  message?: string | undefined;
+  name?: string | undefined;
+  traceback?: string[] | undefined;
+}, {
+  message?: string | undefined;
+  name?: string | undefined;
+  traceback?: string[] | undefined;
+}>>;
+type ExecutionError = z.infer<typeof executionErrorSchema>;
+declare const executionSchema: z.ZodOptional<z.ZodObject<{
+  error: z.ZodOptional<z.ZodObject<{
+    message: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    traceback: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+  }, "strip", z.ZodTypeAny, {
+    message?: string | undefined;
+    name?: string | undefined;
+    traceback?: string[] | undefined;
+  }, {
+    message?: string | undefined;
+    name?: string | undefined;
+    traceback?: string[] | undefined;
+  }>>;
+  finishedAt: z.ZodOptional<z.ZodString>;
+  inputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  startedAt: z.ZodOptional<z.ZodString>;
+  summary: z.ZodOptional<z.ZodObject<{
+    blocksExecuted: z.ZodOptional<z.ZodNumber>;
+    blocksFailed: z.ZodOptional<z.ZodNumber>;
+    blocksSucceeded: z.ZodOptional<z.ZodNumber>;
+    totalDurationMs: z.ZodOptional<z.ZodNumber>;
+  }, "strip", z.ZodTypeAny, {
+    blocksExecuted?: number | undefined;
+    blocksFailed?: number | undefined;
+    blocksSucceeded?: number | undefined;
+    totalDurationMs?: number | undefined;
+  }, {
+    blocksExecuted?: number | undefined;
+    blocksFailed?: number | undefined;
+    blocksSucceeded?: number | undefined;
+    totalDurationMs?: number | undefined;
+  }>>;
+  triggeredBy: z.ZodOptional<z.ZodEnum<["user", "schedule", "api", "ci"]>>;
+}, "strip", z.ZodTypeAny, {
+  error?: {
+    message?: string | undefined;
+    name?: string | undefined;
+    traceback?: string[] | undefined;
+  } | undefined;
+  finishedAt?: string | undefined;
+  inputs?: Record<string, unknown> | undefined;
+  startedAt?: string | undefined;
+  summary?: {
+    blocksExecuted?: number | undefined;
+    blocksFailed?: number | undefined;
+    blocksSucceeded?: number | undefined;
+    totalDurationMs?: number | undefined;
+  } | undefined;
+  triggeredBy?: "user" | "schedule" | "api" | "ci" | undefined;
+}, {
+  error?: {
+    message?: string | undefined;
+    name?: string | undefined;
+    traceback?: string[] | undefined;
+  } | undefined;
+  finishedAt?: string | undefined;
+  inputs?: Record<string, unknown> | undefined;
+  startedAt?: string | undefined;
+  summary?: {
+    blocksExecuted?: number | undefined;
+    blocksFailed?: number | undefined;
+    blocksSucceeded?: number | undefined;
+    totalDurationMs?: number | undefined;
+  } | undefined;
+  triggeredBy?: "user" | "schedule" | "api" | "ci" | undefined;
+}>>;
+type Execution = z.infer<typeof executionSchema>;
 declare const deepnoteFileSchema: z.ZodObject<{
+  environment: z.ZodOptional<z.ZodObject<{
+    customImage: z.ZodOptional<z.ZodString>;
+    hash: z.ZodOptional<z.ZodString>;
+    packages: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    platform: z.ZodOptional<z.ZodString>;
+    python: z.ZodOptional<z.ZodObject<{
+      environment: z.ZodOptional<z.ZodEnum<["uv", "conda", "venv", "poetry", "system"]>>;
+      version: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+      version?: string | undefined;
+      environment?: "uv" | "conda" | "venv" | "poetry" | "system" | undefined;
+    }, {
+      version?: string | undefined;
+      environment?: "uv" | "conda" | "venv" | "poetry" | "system" | undefined;
+    }>>;
+  }, "strip", z.ZodTypeAny, {
+    customImage?: string | undefined;
+    hash?: string | undefined;
+    packages?: Record<string, string> | undefined;
+    platform?: string | undefined;
+    python?: {
+      version?: string | undefined;
+      environment?: "uv" | "conda" | "venv" | "poetry" | "system" | undefined;
+    } | undefined;
+  }, {
+    customImage?: string | undefined;
+    hash?: string | undefined;
+    packages?: Record<string, string> | undefined;
+    platform?: string | undefined;
+    python?: {
+      version?: string | undefined;
+      environment?: "uv" | "conda" | "venv" | "poetry" | "system" | undefined;
+    } | undefined;
+  }>>;
+  execution: z.ZodOptional<z.ZodObject<{
+    error: z.ZodOptional<z.ZodObject<{
+      message: z.ZodOptional<z.ZodString>;
+      name: z.ZodOptional<z.ZodString>;
+      traceback: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+      message?: string | undefined;
+      name?: string | undefined;
+      traceback?: string[] | undefined;
+    }, {
+      message?: string | undefined;
+      name?: string | undefined;
+      traceback?: string[] | undefined;
+    }>>;
+    finishedAt: z.ZodOptional<z.ZodString>;
+    inputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    startedAt: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodObject<{
+      blocksExecuted: z.ZodOptional<z.ZodNumber>;
+      blocksFailed: z.ZodOptional<z.ZodNumber>;
+      blocksSucceeded: z.ZodOptional<z.ZodNumber>;
+      totalDurationMs: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+      blocksExecuted?: number | undefined;
+      blocksFailed?: number | undefined;
+      blocksSucceeded?: number | undefined;
+      totalDurationMs?: number | undefined;
+    }, {
+      blocksExecuted?: number | undefined;
+      blocksFailed?: number | undefined;
+      blocksSucceeded?: number | undefined;
+      totalDurationMs?: number | undefined;
+    }>>;
+    triggeredBy: z.ZodOptional<z.ZodEnum<["user", "schedule", "api", "ci"]>>;
+  }, "strip", z.ZodTypeAny, {
+    error?: {
+      message?: string | undefined;
+      name?: string | undefined;
+      traceback?: string[] | undefined;
+    } | undefined;
+    finishedAt?: string | undefined;
+    inputs?: Record<string, unknown> | undefined;
+    startedAt?: string | undefined;
+    summary?: {
+      blocksExecuted?: number | undefined;
+      blocksFailed?: number | undefined;
+      blocksSucceeded?: number | undefined;
+      totalDurationMs?: number | undefined;
+    } | undefined;
+    triggeredBy?: "user" | "schedule" | "api" | "ci" | undefined;
+  }, {
+    error?: {
+      message?: string | undefined;
+      name?: string | undefined;
+      traceback?: string[] | undefined;
+    } | undefined;
+    finishedAt?: string | undefined;
+    inputs?: Record<string, unknown> | undefined;
+    startedAt?: string | undefined;
+    summary?: {
+      blocksExecuted?: number | undefined;
+      blocksFailed?: number | undefined;
+      blocksSucceeded?: number | undefined;
+      totalDurationMs?: number | undefined;
+    } | undefined;
+    triggeredBy?: "user" | "schedule" | "api" | "ci" | undefined;
+  }>>;
   metadata: z.ZodObject<{
     checksum: z.ZodOptional<z.ZodString>;
     createdAt: z.ZodString;
@@ -97,7 +341,10 @@ declare const deepnoteFileSchema: z.ZodObject<{
       blocks: z.ZodArray<z.ZodObject<{
         blockGroup: z.ZodOptional<z.ZodString>;
         content: z.ZodOptional<z.ZodString>;
+        contentHash: z.ZodOptional<z.ZodString>;
         executionCount: z.ZodOptional<z.ZodNumber>;
+        executionFinishedAt: z.ZodOptional<z.ZodString>;
+        executionStartedAt: z.ZodOptional<z.ZodString>;
         id: z.ZodString;
         metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
         outputs: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
@@ -110,7 +357,10 @@ declare const deepnoteFileSchema: z.ZodObject<{
         sortingKey: string;
         blockGroup?: string | undefined;
         content?: string | undefined;
+        contentHash?: string | undefined;
         executionCount?: number | undefined;
+        executionFinishedAt?: string | undefined;
+        executionStartedAt?: string | undefined;
         metadata?: Record<string, any> | undefined;
         outputs?: any[] | undefined;
         version?: number | undefined;
@@ -120,7 +370,10 @@ declare const deepnoteFileSchema: z.ZodObject<{
         sortingKey: string;
         blockGroup?: string | undefined;
         content?: string | undefined;
+        contentHash?: string | undefined;
         executionCount?: number | undefined;
+        executionFinishedAt?: string | undefined;
+        executionStartedAt?: string | undefined;
         metadata?: Record<string, any> | undefined;
         outputs?: any[] | undefined;
         version?: number | undefined;
@@ -139,7 +392,10 @@ declare const deepnoteFileSchema: z.ZodObject<{
         sortingKey: string;
         blockGroup?: string | undefined;
         content?: string | undefined;
+        contentHash?: string | undefined;
         executionCount?: number | undefined;
+        executionFinishedAt?: string | undefined;
+        executionStartedAt?: string | undefined;
         metadata?: Record<string, any> | undefined;
         outputs?: any[] | undefined;
         version?: number | undefined;
@@ -156,7 +412,10 @@ declare const deepnoteFileSchema: z.ZodObject<{
         sortingKey: string;
         blockGroup?: string | undefined;
         content?: string | undefined;
+        contentHash?: string | undefined;
         executionCount?: number | undefined;
+        executionFinishedAt?: string | undefined;
+        executionStartedAt?: string | undefined;
         metadata?: Record<string, any> | undefined;
         outputs?: any[] | undefined;
         version?: number | undefined;
@@ -166,6 +425,10 @@ declare const deepnoteFileSchema: z.ZodObject<{
       workingDirectory?: string | undefined;
     }>, "many">;
     settings: z.ZodOptional<z.ZodObject<{
+      /**
+       * @deprecated Use top-level `environment` instead.
+       * This field is kept for backward compatibility.
+       */
       environment: z.ZodOptional<z.ZodObject<{
         customImage: z.ZodOptional<z.ZodString>;
         pythonVersion: z.ZodOptional<z.ZodString>;
@@ -205,7 +468,10 @@ declare const deepnoteFileSchema: z.ZodObject<{
         sortingKey: string;
         blockGroup?: string | undefined;
         content?: string | undefined;
+        contentHash?: string | undefined;
         executionCount?: number | undefined;
+        executionFinishedAt?: string | undefined;
+        executionStartedAt?: string | undefined;
         metadata?: Record<string, any> | undefined;
         outputs?: any[] | undefined;
         version?: number | undefined;
@@ -240,7 +506,10 @@ declare const deepnoteFileSchema: z.ZodObject<{
         sortingKey: string;
         blockGroup?: string | undefined;
         content?: string | undefined;
+        contentHash?: string | undefined;
         executionCount?: number | undefined;
+        executionFinishedAt?: string | undefined;
+        executionStartedAt?: string | undefined;
         metadata?: Record<string, any> | undefined;
         outputs?: any[] | undefined;
         version?: number | undefined;
@@ -285,7 +554,10 @@ declare const deepnoteFileSchema: z.ZodObject<{
         sortingKey: string;
         blockGroup?: string | undefined;
         content?: string | undefined;
+        contentHash?: string | undefined;
         executionCount?: number | undefined;
+        executionFinishedAt?: string | undefined;
+        executionStartedAt?: string | undefined;
         metadata?: Record<string, any> | undefined;
         outputs?: any[] | undefined;
         version?: number | undefined;
@@ -309,6 +581,33 @@ declare const deepnoteFileSchema: z.ZodObject<{
       sqlCacheMaxAge?: number | undefined;
     } | undefined;
   };
+  environment?: {
+    customImage?: string | undefined;
+    hash?: string | undefined;
+    packages?: Record<string, string> | undefined;
+    platform?: string | undefined;
+    python?: {
+      version?: string | undefined;
+      environment?: "uv" | "conda" | "venv" | "poetry" | "system" | undefined;
+    } | undefined;
+  } | undefined;
+  execution?: {
+    error?: {
+      message?: string | undefined;
+      name?: string | undefined;
+      traceback?: string[] | undefined;
+    } | undefined;
+    finishedAt?: string | undefined;
+    inputs?: Record<string, unknown> | undefined;
+    startedAt?: string | undefined;
+    summary?: {
+      blocksExecuted?: number | undefined;
+      blocksFailed?: number | undefined;
+      blocksSucceeded?: number | undefined;
+      totalDurationMs?: number | undefined;
+    } | undefined;
+    triggeredBy?: "user" | "schedule" | "api" | "ci" | undefined;
+  } | undefined;
 }, {
   metadata: {
     createdAt: string;
@@ -329,7 +628,10 @@ declare const deepnoteFileSchema: z.ZodObject<{
         sortingKey: string;
         blockGroup?: string | undefined;
         content?: string | undefined;
+        contentHash?: string | undefined;
         executionCount?: number | undefined;
+        executionFinishedAt?: string | undefined;
+        executionStartedAt?: string | undefined;
         metadata?: Record<string, any> | undefined;
         outputs?: any[] | undefined;
         version?: number | undefined;
@@ -353,6 +655,33 @@ declare const deepnoteFileSchema: z.ZodObject<{
       sqlCacheMaxAge?: number | undefined;
     } | undefined;
   };
+  environment?: {
+    customImage?: string | undefined;
+    hash?: string | undefined;
+    packages?: Record<string, string> | undefined;
+    platform?: string | undefined;
+    python?: {
+      version?: string | undefined;
+      environment?: "uv" | "conda" | "venv" | "poetry" | "system" | undefined;
+    } | undefined;
+  } | undefined;
+  execution?: {
+    error?: {
+      message?: string | undefined;
+      name?: string | undefined;
+      traceback?: string[] | undefined;
+    } | undefined;
+    finishedAt?: string | undefined;
+    inputs?: Record<string, unknown> | undefined;
+    startedAt?: string | undefined;
+    summary?: {
+      blocksExecuted?: number | undefined;
+      blocksFailed?: number | undefined;
+      blocksSucceeded?: number | undefined;
+      totalDurationMs?: number | undefined;
+    } | undefined;
+    triggeredBy?: "user" | "schedule" | "api" | "ci" | undefined;
+  } | undefined;
 }>;
 type DeepnoteFile = z.infer<typeof deepnoteFileSchema>;
 //#endregion
@@ -362,6 +691,24 @@ type DeepnoteFile = z.infer<typeof deepnoteFileSchema>;
  */
 declare function deserializeDeepnoteFile(yamlContent: string): DeepnoteFile;
 //#endregion
+//#region src/deserialize-file/parse-yaml.d.ts
+/**
+ * Validates UTF-8 encoding from raw bytes before decoding to string.
+ * This is the proper way to validate UTF-8 - check BEFORE decoding.
+ *
+ * @param bytes - Raw file bytes as Uint8Array
+ * @returns Decoded UTF-8 string without BOM
+ * @throws Error if BOM detected or invalid UTF-8 encoding
+ *
+ * @example
+ * ```typescript
+ * const bytes = await fs.readFile('file.deepnote') // Returns Buffer/Uint8Array
+ * const yamlContent = decodeUtf8NoBom(bytes)
+ * const parsed = parseYaml(yamlContent)
+ * ```
+ */
+declare function decodeUtf8NoBom(bytes: Uint8Array): string;
+//#endregion
 //#region src/markdown.d.ts
 declare function createMarkdown(block: DeepnoteBlock): string;
 declare function stripMarkdown(block: DeepnoteBlock): string;
@@ -378,4 +725,4 @@ interface ButtonExecutionContext {
 //#region src/python-code.d.ts
 declare function createPythonCode(block: DeepnoteBlock, executionContext?: ButtonExecutionContext): string;
 //#endregion
-export { type DeepnoteBlock, type DeepnoteFile, type TableState, createMarkdown, createPythonCode, deepnoteBlockSchema, deserializeDeepnoteFile, stripMarkdown };
+export { type DeepnoteBlock, type DeepnoteFile, type Environment, type Execution, type ExecutionError, type ExecutionSummary, type TableState, createMarkdown, createPythonCode, decodeUtf8NoBom, deepnoteBlockSchema, deepnoteFileSchema, deserializeDeepnoteFile, environmentSchema, executionErrorSchema, executionSchema, executionSummarySchema, stripMarkdown };

package/dist/index.js

@@ -1,12 +1,15 @@
 import { z } from "zod";
-import { parse } from "yaml";
+import { parseDocument } from "yaml";
 import { dedent } from "ts-dedent";
 
 //#region src/deserialize-file/deepnote-file-schema.ts
 const deepnoteBlockSchema = z.object({
 	blockGroup: z.string().optional(),
 	content: z.string().optional(),
+	contentHash: z.string().regex(/^(md5|sha256):[a-f0-9]+$/i).optional(),
 	executionCount: z.number().optional(),
+	executionFinishedAt: z.string().datetime().optional(),
+	executionStartedAt: z.string().datetime().optional(),
 	id: z.string(),
 	metadata: z.record(z.any()).optional(),
 	outputs: z.array(z.any()).optional(),
@@ -14,7 +17,49 @@ const deepnoteBlockSchema = z.object({
 	type: z.string(),
 	version: z.number().optional()
 });
+const environmentSchema = z.object({
+	customImage: z.string().optional(),
+	hash: z.string().optional(),
+	packages: z.record(z.string()).optional(),
+	platform: z.string().optional(),
+	python: z.object({
+		environment: z.enum([
+			"uv",
+			"conda",
+			"venv",
+			"poetry",
+			"system"
+		]).optional(),
+		version: z.string().optional()
+	}).optional()
+}).optional();
+const executionSummarySchema = z.object({
+	blocksExecuted: z.number().int().nonnegative().optional(),
+	blocksFailed: z.number().int().nonnegative().optional(),
+	blocksSucceeded: z.number().int().nonnegative().optional(),
+	totalDurationMs: z.number().nonnegative().optional()
+}).optional();
+const executionErrorSchema = z.object({
+	message: z.string().optional(),
+	name: z.string().optional(),
+	traceback: z.array(z.string()).optional()
+}).optional();
+const executionSchema = z.object({
+	error: executionErrorSchema,
+	finishedAt: z.string().datetime().optional(),
+	inputs: z.record(z.unknown()).optional(),
+	startedAt: z.string().datetime().optional(),
+	summary: executionSummarySchema,
+	triggeredBy: z.enum([
+		"user",
+		"schedule",
+		"api",
+		"ci"
+	]).optional()
+}).optional();
 const deepnoteFileSchema = z.object({
+	environment: environmentSchema,
+	execution: executionSchema,
 	metadata: z.object({
 		checksum: z.string().optional(),
 		createdAt: z.string(),
@@ -52,9 +97,88 @@ const deepnoteFileSchema = z.object({
 
 //#endregion
 //#region src/deserialize-file/parse-yaml.ts
+/**
+* Validates UTF-8 encoding from raw bytes before decoding to string.
+* This is the proper way to validate UTF-8 - check BEFORE decoding.
+*
+* @param bytes - Raw file bytes as Uint8Array
+* @returns Decoded UTF-8 string without BOM
+* @throws Error if BOM detected or invalid UTF-8 encoding
+*
+* @example
+* ```typescript
+* const bytes = await fs.readFile('file.deepnote') // Returns Buffer/Uint8Array
+* const yamlContent = decodeUtf8NoBom(bytes)
+* const parsed = parseYaml(yamlContent)
+* ```
+*/
+function decodeUtf8NoBom(bytes) {
+	if (bytes.length >= 3 && bytes[0] === 239 && bytes[1] === 187 && bytes[2] === 191) throw new Error("UTF-8 BOM detected in Deepnote file - files must be UTF-8 without BOM");
+	try {
+		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch {
+		throw new Error("Invalid UTF-8 encoding detected in Deepnote file");
+	}
+}
+/**
+* Validates that a string doesn't start with BOM.
+* Note: This is a fallback when only a string is available.
+* By the time we have a JS string, invalid UTF-8 has already been handled during decoding.
+* For proper UTF-8 validation, use decodeUtf8NoBom() on raw bytes before decoding.
+*
+* @param yamlContent - Already-decoded YAML string
+* @throws Error if BOM prefix detected
+*/
+function validateNoBomPrefix(yamlContent) {
+	if (yamlContent.charCodeAt(0) === 65279) throw new Error("UTF-8 BOM detected in Deepnote file - files must be UTF-8 without BOM");
+}
+/**
+* Validates that the YAML document doesn't contain prohibited features:
+* - No anchors/aliases (&anchor, *alias)
+* - No merge keys (<<)
+* - No custom tags (!tag)
+*/
+function validateYamlStructure(yamlContent) {
+	if (/(?:^|\n)\s*(?:-\s+|[\w-]+:\s*)&\w+/.test(yamlContent)) throw new Error("YAML anchors (&) are not allowed in Deepnote files");
+	if (/(?:^|\n)\s*(?:-\s+|[\w-]+:\s*)\*\w+/.test(yamlContent)) throw new Error("YAML aliases (*) are not allowed in Deepnote files");
+	if (/<<:/.test(yamlContent)) throw new Error("YAML merge keys (<<) are not allowed in Deepnote files");
+	const matches = yamlContent.match(/(?:^|\n)\s*(?:-\s+|[\w-]+:\s*)(![\w/-]+)/gm);
+	if (matches) {
+		const tags = matches.map((m) => m.match(/(![\w/-]+)/)?.[1]).filter(Boolean);
+		if (tags.length > 0) throw new Error(`YAML tags are not allowed in Deepnote files: ${tags.join(", ")}`);
+	}
+}
+/**
+* Parse and validate YAML document in a single pass.
+* Checks for duplicate keys and other parsing errors, then converts to JavaScript object.
+*/
+function parseAndValidate(yamlContent) {
+	const doc = parseDocument(yamlContent, {
+		strict: true,
+		uniqueKeys: true,
+		version: "1.2"
+	});
+	if (doc.errors.length > 0) {
+		const duplicateKeyError = doc.errors.find((err) => err.message.includes("duplicate") || err.message.includes("key"));
+		if (duplicateKeyError) throw new Error(`Duplicate keys detected in Deepnote file: ${duplicateKeyError.message}`);
+		throw new Error(`YAML parsing error: ${doc.errors[0].message}`);
+	}
+	return doc.toJS();
+}
+/**
+* Parse YAML content with strict validation rules:
+* - YAML 1.2 only
+* - UTF-8 only
+* - No duplicate keys
+* - No anchors/aliases/merge keys
+* - No custom tags
+* - Explicit typing enforced by schema
+*/
 function parseYaml(yamlContent) {
 	try {
-		return parse(yamlContent);
+		validateNoBomPrefix(yamlContent);
+		validateYamlStructure(yamlContent);
+		return parseAndValidate(yamlContent);
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		throw new Error(`Failed to parse Deepnote file: ${message}`);
@@ -565,4 +689,4 @@ function createPythonCode(block, executionContext) {
 }
 
 //#endregion
-export { createMarkdown, createPythonCode, deepnoteBlockSchema, deserializeDeepnoteFile, stripMarkdown };
+export { createMarkdown, createPythonCode, decodeUtf8NoBom, deepnoteBlockSchema, deepnoteFileSchema, deserializeDeepnoteFile, environmentSchema, executionErrorSchema, executionSchema, executionSummarySchema, stripMarkdown };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepnote/blocks",
-  "version": "1.3.5",
+  "version": "1.4.0",
   "description": "",
   "keywords": [],
   "repository": {
@@ -31,6 +31,10 @@
     "yaml": "^2.8.1",
     "zod": "3.25.76"
   },
+  "engines": {
+    "node": ">=22.14.0",
+    "pnpm": ">=10.17.1"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"