kayg/calternal

Watch

Fork 0

DOCS: explain Calendar client and credential crypto contracts #928

New issue

Open

opened 2026-10-02 17:40:37 +00:00 by kayg · 2 comments

kayg commented

2026-10-02 17:40:37 +00:00

Owner

Evidence

At the #863 audit base, the public-function scan found 34 functions in crates/plugins/calendar/src without adjacent docs. Non-obvious examples include client/mod.rs:188 (discover), :275 (sync_collection), and cache/crypto.rs:105,134 (encrypt and decrypt). The crypto methods bind authentication data to the User, Connected Account, and credential kind; encryption uses a fresh 24-byte nonce.
A case-sensitive scan found two comment lines in feeds/publication.rs that name common third-party products. Examples: :1526 names a platform; :2095 names a calendar-import provider.

Owner rule

Comments are documentation. Each non-obvious function needs a short, current comment. Source comments must not name third-party products.

Expected behaviour

Document discovery, collection sync, and credential associated-data and nonce invariants. Describe import compatibility as a format rule, without vendor names. Preserve Calendar API and encryption behavior.

Test idea

Review comments against the existing Calendar client, feed, and crypto tests. Keep cryptographic and wire expectations unchanged.

## Evidence At the #863 audit base, the public-function scan found 34 functions in `crates/plugins/calendar/src` without adjacent docs. Non-obvious examples include `client/mod.rs:188` (`discover`), `:275` (`sync_collection`), and `cache/crypto.rs:105,134` (`encrypt` and `decrypt`). The crypto methods bind authentication data to the User, Connected Account, and credential kind; encryption uses a fresh 24-byte nonce. A case-sensitive scan found two comment lines in `feeds/publication.rs` that name common third-party products. Examples: `:1526` names a platform; `:2095` names a calendar-import provider. ## Owner rule Comments are documentation. Each non-obvious function needs a short, current comment. Source comments must not name third-party products. ## Expected behaviour Document discovery, collection sync, and credential associated-data and nonce invariants. Describe import compatibility as a format rule, without vendor names. Preserve Calendar API and encryption behavior. ## Test idea Review comments against the existing Calendar client, feed, and crypto tests. Keep cryptographic and wire expectations unchanged.

kayg referenced this issue

2026-10-02 17:44:36 +00:00

Audit: module docs and stale comments (comments are docs) #863

kayg commented

2026-10-02 17:55:01 +00:00

Author

Owner

Fixed the Rust comment findings in crates/plugins/calendar. Document discovery sync and credential authentication contracts. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged.

Commit: 325fbfce948df4e88329797eede8ccdf1b24b8ef.

Verification: cargo fmt --check exited 0; output was empty. A source comparison with full-line comments removed matched before and after for every changed file.

Files:

crates/plugins/calendar/src/cache/crypto.rs
crates/plugins/calendar/src/client/mod.rs
crates/plugins/calendar/src/feeds/publication.rs

Decision: use protocol, format, and calternal domain terms in place of product names. No behavior decision. Issues remain open.

Fixed the Rust comment findings in `crates/plugins/calendar`. Document discovery sync and credential authentication contracts. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged. Commit: `325fbfce948df4e88329797eede8ccdf1b24b8ef`. Verification: `cargo fmt --check` exited 0; output was empty. A source comparison with full-line comments removed matched before and after for every changed file. Files: - `crates/plugins/calendar/src/cache/crypto.rs` - `crates/plugins/calendar/src/client/mod.rs` - `crates/plugins/calendar/src/feeds/publication.rs` Decision: use protocol, format, and calternal domain terms in place of product names. No behavior decision. Issues remain open.

kayg referenced this issue from a commit

2026-10-02 17:56:13 +00:00

docs: document discovery sync and credential authentication contracts (#928)

kayg commented

2026-10-02 18:02:37 +00:00

Author

Owner

Rust comment fixes are complete on job/docsfix-rust. Final commit: af23bb254fe990fe7ed03934f5bc569b9d8e4526. This is the retained atomic commit after the final prose review; it supersedes any earlier SHA posted for this work.

docs: document discovery sync and credential authentication contracts (#928)

All executable source and test expectations are unchanged. The final comparison against origin/dev confirmed only full-line comments and blank lines changed. The audited product-name scan passed across non-vendored Rust comments.

Gate: cargo fmt --check exited 0. Verbatim stdout and stderr are empty:

Files:

crates/plugins/calendar/src/cache/crypto.rs
crates/plugins/calendar/src/client/mod.rs
crates/plugins/calendar/src/feeds/publication.rs

Decision: describe existing behavior with protocol, format, and calternal domain terms; no behavior or design change. No build or behavior tests ran, as required by this comment-only job. No issue is closed.

Rust comment fixes are complete on `job/docsfix-rust`. Final commit: `af23bb254fe990fe7ed03934f5bc569b9d8e4526`. This is the retained atomic commit after the final prose review; it supersedes any earlier SHA posted for this work. docs: document discovery sync and credential authentication contracts (#928) All executable source and test expectations are unchanged. The final comparison against `origin/dev` confirmed only full-line comments and blank lines changed. The audited product-name scan passed across non-vendored Rust comments. Gate: `cargo fmt --check` exited 0. Verbatim stdout and stderr are empty: ```text ``` Files: - `crates/plugins/calendar/src/cache/crypto.rs` - `crates/plugins/calendar/src/client/mod.rs` - `crates/plugins/calendar/src/feeds/publication.rs` Decision: describe existing behavior with protocol, format, and calternal domain terms; no behavior or design change. No build or behavior tests ran, as required by this comment-only job. No issue is closed.

kayg referenced this issue

2026-10-02 18:02:42 +00:00

Audit: module docs and stale comments (comments are docs) #863

kayg referenced this issue from a commit

2026-10-02 18:10:46 +00:00

docs: document discovery sync and credential authentication contracts (#928)

kayg referenced this issue

2026-10-03 00:35:56 +00:00

Audit: module docs and stale comments (comments are docs) #863

kayg referenced this issue

2026-10-03 00:35:56 +00:00

DOCS: remove product names from AI provider comments #923